Lease File

The Lease File operation creates and manages a lock on a file for write and delete operations. Lease File is supported for version 2019-02-02 and later.

You can call the Lease File operation in one of the following modes:

  • Acquire, to request a new lease.
  • Change, to change the ID of an existing lease.
  • Release, to free the lease if it's no longer needed, so that another client can immediately acquire a lease against the file.
  • Break, to forcibly end the lease, but ensure that another client can't acquire a new lease until the current lease period has expired.

Protocol availability

Enabled file share protocol Available


You can construct the Lease File request as follows. HTTPS is recommended.

Method Request URI HTTP version
Put HTTP/1.1

Replace the path components shown in the request URI with your own, as follows:

Path component Description
myaccount The name of your storage account.
myshare The name of your file share.
mydirectorypath Optional. The path to the directory.
myfile The name of the file.

URI parameters

You can specify the following additional parameter on the request URI.

Parameter Description
timeout Optional. The timeout parameter is expressed in seconds. For more information, see Setting timeouts for Azure Files operations.

Request headers

The following table describes required and optional request headers.

Request header Description
Authorization Required. Specifies the authorization scheme, account name, and signature. For more information, see Authorize requests to Azure Storage.
Date or x-ms-date Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authorize requests to Azure Storage.
x-ms-version Optional. Specifies the version of the operation to use for this request. For more information, see Versioning for the Azure Storage services.
x-ms-lease-id: <ID> Required to renew, change, or release the lease.

You can specify the value of x-ms-lease-id in any valid, GUID string format. See Guid Constructor (String) for a list of valid formats.
x-ms-lease-action: <acquire ¦ change ¦ release ¦ break> acquire: Requests a new lease. If the file doesn't have an active lease, Azure Files creates a lease on the file, and returns a new lease ID. If the file has an active lease, you can only request a new lease by using the active lease ID.

change: Changes the lease ID of an active lease. A change must include the current lease ID in x-ms-lease-id, and a new lease ID in x-ms-proposed-lease-id.

release: Releases the lease. You can release the lease if the lease ID specified on the request matches that associated with the file. Releasing the lease allows another client to immediately acquire the lease for the file, as soon as the release is complete.

break: Breaks the lease, if the file has an active lease. Any authorized request can break the lease. The request isn't required to specify a matching lease ID. An infinite lease is broken immediately.
x-ms-lease-duration: -1 Allowed and required only on an acquire operation. Required to be -1, to indicate a lease that never expires.
x-ms-proposed-lease-id: <ID> Optional for acquire, and required for change. Proposed lease ID, in a GUID string format. Azure Files returns 400 (Invalid request) if the proposed lease ID isn't in the correct format. See Guid Constructor (String) for a list of valid formats.
x-ms-client-request-id Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit that's recorded in the logs when logging is configured. We highly recommend that you use this header to correlate client-side activities with requests that the server receives. For more information, see Monitor Azure Files.
x-ms-file-request-intent Required if Authorization header specifies an OAuth token. Acceptable value is backup. This header specifies that the Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action or Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action should be granted if they are included in the RBAC policy assigned to the identity that is authorized using the Authorization header. Available for version 2022-11-02 and later.
x-ms-allow-trailing-dot: { <Boolean> } Optional. Version 2022-11-02 and later. The Boolean value specifies if a trailing dot present in request url should be trimmed or not. For more information, see Naming and referencing shares, directories, files, and metadata.

Request body


Sample request

The following sample request shows how to acquire a lease:

Request Syntax:  
PUT HTTP/1.1  
Request Headers:  
x-ms-version: 2019-07-07  
x-ms-lease-action: acquire  
x-ms-lease-duration: -1  
x-ms-proposed-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-date: <date>  
Authorization: SharedKey testaccount1:esSKMOYdK4o+nGTuTyeOLBI+xqnqi6aBmiW4XI699+o=  


The response includes an HTTP status code and a set of response headers.

Status code

The success status codes returned for lease operations are the following:

  • Acquire: A successful operation returns status code 201 (Created).
  • Change: A successful operation returns status code 200 (OK).
  • Release: A successful operation returns status code 200 (OK).
  • Break: A successful operation returns status code 202 (Accepted).

For information about status codes, see Status and error codes.

Response headers

The response for this operation includes the following headers. The response can also include additional, standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Syntax Description
ETag Contains a value that you can use to perform operations conditionally, in quotes. The Lease File operation doesn't modify this property.
Last-Modified The date/time that the file was last modified. For more information, see Representation of date-time values in headers.

Any write operation on the file, including updates on the file's metadata or properties, changes the last-modified time of the file. The Lease File operation doesn't modify this property.
x-ms-lease-id: <id> When you request a lease, Azure Files returns a unique lease ID. While the lease is active, you must include the lease ID with any request to write to the file, or to change, or release the lease.

A successful renew operation also returns the lease ID for the active lease.
x-ms-lease-time: seconds Returned only for a successful request to break the lease. 0 is returned for immediate breaks.
x-ms-request-id Uniquely identifies the request that was made, and can be used for troubleshooting the request. For more information, see Troubleshooting API operations.
x-ms-version Indicates the version of Azure Files used to run the request.
Date A UTC date/time value that indicates the time at which the response was initiated. The service generates this value.
x-ms-client-request-id Can be used to troubleshoot requests and corresponding responses. The value of this header is equal to the value of the x-ms-client-request-id header, if it's present in the request. The value is at most 1,024 visible ASCII characters. If the x-ms-client-request-id header isn't present in the request, it won't be present in the response.

Response body


Sample response

The following is a sample response for a request to acquire a lease:

Response Status:  
HTTP/1.1 201 Created  
Response Headers:  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402  
x-ms-version: 2019-07-07
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
Date: <date>  


The account owner can call this operation. Additionally, any client with a shared access signature that has permission to write to this file or its share can do so.


A lease on a file provides exclusive write and delete access to the file. To write to a file with an active lease, a client must include the active lease ID with the write request. The lease is granted for an infinite duration.

When a client acquires a lease, a lease ID is returned. Azure Files generates a lease ID if one isn't specified in the acquire request. The client can use this lease ID to change its lease ID or release the lease.

When a lease is active, the lease ID must be included in the request for any of the following operations:

If the lease ID isn't included, these operations fail on a leased file, with 412 – Precondition failed.

The following operations succeed on a leased file, without including the lease ID:

It's not necessary to include the lease ID for GET operations on a file that has an active lease. However, all GET operations support a conditional lease parameter. In this type of parameter, the operation only proceeds if the lease ID included with the request is valid.

All share operations are permitted on a share that includes files with an active lease, including Delete Share. Therefore, you can delete a share even if files within it have active leases.

Lease states

The following diagram shows the three states of a lease, and the commands or events that cause lease state changes.

Diagram that shows file lease states and state change triggers.

A lease can be in three states, based on whether the lease is locked or unlocked, and whether the lease is renewable in that state. The lease actions shown in the preceding diagram cause state transitions.

  • Available: The lease is unlocked and can be acquired. Allowed action: acquire.
  • Leased: The lease is locked. Allowed actions: acquire (same lease ID only), change, release, and break.
  • Broken: The lease has been broken. Allowed actions: acquire, release, and break.

Note that a lease can't be granted for a file in a share snapshot, because snapshots are read-only. Requesting a lease against a file in a share snapshot results in status code 400 (Bad Request).

The file's Last-Modified-Time property isn't updated by calls to Lease File.

The following tables show outcomes of actions on files with leases in various lease states. Letters (A), (B), and (C) represent lease IDs, and (X) represents a lease ID generated by Azure Files.

Outcomes of use attempts on files by lease state

Action Available Leased (A) Broken (A)
Write by using (A) Fails (412) Leased (A), write succeeds Fails (412)
Write by using (B) Fails (412) Fails (409) Fails (412)
Write, no lease specified Available, write succeeds Fails (412) Available, write succeeds
Read by using (A) Fails (412) Leased (A), read succeeds Fails (412)
Read by using (B) Fails (412) Fails (409) Fails (412)
Read, no lease specified Available, read succeeds Leased (A), read succeeds Broken (A), read succeeds

Outcomes of lease operations on files by lease state

Action Available Leased (A) Broken (A)
Acquire, no proposed lease ID Leased (X) Fails (409) Leased (X)
Acquire (A) Leased (A) Leased (A) Leased (A)
Acquire (B) Leased (B) Fails (409) Leased (B)
Break Fails (409) Broken (A) Broken (A)
Change, (A) to (B) Fails (409) Leased (B) Fails (409)
Change, (B) to (A) Fails (409) Leased (A) Fails (409)
Change, (B) to (C) Fails (409) Fails (409) Fails (409)
Release (A) Fails (409) Available Available
Release (B) Fails (409) Fails (409) Fails (409)

See also