[Storage] Fix double encoding of path names on Datalake clients

sdk/storage/azure-storage-file-datalake/CHANGELOG.md

@@ -7,8 +7,14 @@
 ### Breaking Changes
 
 ### Bugs Fixed
+- Fixed a bug where the client returned by `rename`, `renameWithResponse`, and `undeletePath` URL-encoded the path
+  name a second time, causing subsequent requests made through that client to target a double-encoded path when the
+  name contained characters such as `%`, `#`, or a space.
 
 ### Other Changes
+- Corrected documentation on `DataLakeFileSystemClient`/`DataLakeFileSystemAsyncClient` path client getters and on
+  `DataLakePathClientBuilder.pathName(String)`, which incorrectly instructed callers to pass a URL-encoded path name.
+  Path names have been used verbatim since 12.22.0 and are percent-encoded by the client when the request URL is built.
 
 ## 12.29.0-beta.1 (2026-07-28)
 

sdk/storage/azure-storage-file-datalake/src/main/java/com/azure/storage/file/datalake/DataLakeDirectoryAsyncClient.java

@@ -21,7 +21,6 @@
 import com.azure.storage.blob.BlobContainerAsyncClient;
 import com.azure.storage.blob.specialized.BlockBlobAsyncClient;
 import com.azure.storage.blob.specialized.SpecializedBlobClientBuilder;
-import com.azure.storage.common.Utility;
 import com.azure.storage.common.implementation.Constants;
 import com.azure.storage.file.datalake.implementation.models.CpkInfo;
 import com.azure.storage.file.datalake.implementation.models.FileSystemsListPathsHeaders;
@@ -91,10 +90,9 @@ public final class DataLakeDirectoryAsyncClient extends DataLakePathAsyncClient
     DataLakeDirectoryAsyncClient(DataLakePathAsyncClient dataLakePathAsyncClient) {
         super(dataLakePathAsyncClient.getHttpPipeline(), dataLakePathAsyncClient.getAccountUrl(),
             dataLakePathAsyncClient.getServiceVersion(), dataLakePathAsyncClient.getAccountName(),
-            dataLakePathAsyncClient.getFileSystemName(), Utility.urlEncode(dataLakePathAsyncClient.pathName),
-            PathResourceType.DIRECTORY, dataLakePathAsyncClient.getBlockBlobAsyncClient(),
-            dataLakePathAsyncClient.getSasToken(), dataLakePathAsyncClient.getCpkInfo(),
-            dataLakePathAsyncClient.isTokenCredentialAuthenticated());
+            dataLakePathAsyncClient.getFileSystemName(), dataLakePathAsyncClient.pathName, PathResourceType.DIRECTORY,
+            dataLakePathAsyncClient.getBlockBlobAsyncClient(), dataLakePathAsyncClient.getSasToken(),
+            dataLakePathAsyncClient.getCpkInfo(), dataLakePathAsyncClient.isTokenCredentialAuthenticated());
     }
 
     /**

sdk/storage/azure-storage-file-datalake/src/main/java/com/azure/storage/file/datalake/DataLakeDirectoryClient.java

@@ -17,7 +17,6 @@
 import com.azure.core.util.Context;
 import com.azure.storage.blob.specialized.BlockBlobClient;
 import com.azure.storage.blob.specialized.SpecializedBlobClientBuilder;
-import com.azure.storage.common.Utility;
 import com.azure.storage.common.implementation.Constants;
 import com.azure.storage.common.implementation.StorageImplUtils;
 import com.azure.storage.file.datalake.implementation.models.CpkInfo;
@@ -77,8 +76,8 @@ public class DataLakeDirectoryClient extends DataLakePathClient {
         super(dataLakePathClient.dataLakePathAsyncClient, dataLakePathClient.blockBlobClient,
             dataLakePathClient.getHttpPipeline(), dataLakePathClient.getAccountUrl(),
             dataLakePathClient.getServiceVersion(), dataLakePathClient.getAccountName(),
-            dataLakePathClient.getFileSystemName(), Utility.urlEncode(dataLakePathClient.pathName),
-            PathResourceType.DIRECTORY, dataLakePathClient.getSasToken(), dataLakePathClient.getCpkInfo(),
+            dataLakePathClient.getFileSystemName(), dataLakePathClient.pathName, PathResourceType.DIRECTORY,
+            dataLakePathClient.getSasToken(), dataLakePathClient.getCpkInfo(),
             dataLakePathClient.isTokenCredentialAuthenticated());
         this.dataLakeDirectoryAsyncClient
             = new DataLakeDirectoryAsyncClient(dataLakePathClient.dataLakePathAsyncClient);

sdk/storage/azure-storage-file-datalake/src/main/java/com/azure/storage/file/datalake/DataLakeFileAsyncClient.java

@@ -24,7 +24,6 @@
 import com.azure.storage.blob.options.BlobDownloadToFileOptions;
 import com.azure.storage.blob.specialized.BlockBlobAsyncClient;
 import com.azure.storage.common.ParallelTransferOptions;
-import com.azure.storage.common.Utility;
 import com.azure.storage.common.implementation.BufferAggregator;
 import com.azure.storage.common.implementation.BufferStagingArea;
 import com.azure.storage.common.implementation.Constants;
@@ -127,10 +126,9 @@ public class DataLakeFileAsyncClient extends DataLakePathAsyncClient {
 
     DataLakeFileAsyncClient(DataLakePathAsyncClient pathAsyncClient) {
         super(pathAsyncClient.getHttpPipeline(), pathAsyncClient.getAccountUrl(), pathAsyncClient.getServiceVersion(),
-            pathAsyncClient.getAccountName(), pathAsyncClient.getFileSystemName(),
-            Utility.urlEncode(pathAsyncClient.pathName), PathResourceType.FILE,
-            pathAsyncClient.getBlockBlobAsyncClient(), pathAsyncClient.getSasToken(), pathAsyncClient.getCpkInfo(),
-            pathAsyncClient.isTokenCredentialAuthenticated());
+            pathAsyncClient.getAccountName(), pathAsyncClient.getFileSystemName(), pathAsyncClient.pathName,
+            PathResourceType.FILE, pathAsyncClient.getBlockBlobAsyncClient(), pathAsyncClient.getSasToken(),
+            pathAsyncClient.getCpkInfo(), pathAsyncClient.isTokenCredentialAuthenticated());
     }
 
     /**

sdk/storage/azure-storage-file-datalake/src/main/java/com/azure/storage/file/datalake/DataLakeFileClient.java

@@ -117,8 +117,8 @@ public class DataLakeFileClient extends DataLakePathClient {
         super(dataLakePathClient.dataLakePathAsyncClient, dataLakePathClient.getBlockBlobClient(),
             dataLakePathClient.getHttpPipeline(), dataLakePathClient.getAccountUrl(),
             dataLakePathClient.getServiceVersion(), dataLakePathClient.getAccountName(),
-            dataLakePathClient.getFileSystemName(), Utility.urlEncode(dataLakePathClient.pathName),
-            PathResourceType.FILE, dataLakePathClient.getSasToken(), dataLakePathClient.getCpkInfo(),
+            dataLakePathClient.getFileSystemName(), dataLakePathClient.pathName, PathResourceType.FILE,
+            dataLakePathClient.getSasToken(), dataLakePathClient.getCpkInfo(),
             dataLakePathClient.isTokenCredentialAuthenticated());
         this.dataLakeFileAsyncClient = new DataLakeFileAsyncClient(dataLakePathClient.dataLakePathAsyncClient);
     }

sdk/storage/azure-storage-file-datalake/src/main/java/com/azure/storage/file/datalake/DataLakeFileSystemAsyncClient.java

@@ -167,8 +167,8 @@ public class DataLakeFileSystemAsyncClient {
      * </pre>
      * <!-- end com.azure.storage.file.datalake.DataLakeFileSystemAsyncClient.getFileAsyncClient#String -->
      *
-     * @param fileName A {@code String} representing the name of the file. If the path name contains special characters,
-     * pass in the url encoded version of the path name.
+     * @param fileName A {@code String} representing the name of the file. Pass the name unencoded; the client
+     * percent-encodes it when building the request URL.
      * @return A new {@link DataLakeFileAsyncClient} object which references the file with the specified name in this
      * file system.
      */
@@ -197,8 +197,8 @@ public DataLakeFileAsyncClient getFileAsyncClient(String fileName) {
      * </pre>
      * <!-- end com.azure.storage.file.datalake.DataLakeFileSystemAsyncClient.getDirectoryAsyncClient#String -->
      *
-     * @param directoryName A {@code String} representing the name of the directory. If the path name contains special
-     * characters, pass in the url encoded version of the path name.
+     * @param directoryName A {@code String} representing the name of the directory.
+     *     Pass the name unencoded; the client percent-encodes it when building the request URL.
      * @return A new {@link DataLakeDirectoryAsyncClient} object which references the directory with the specified name
      * in this file system.
      */
@@ -1220,8 +1220,8 @@ public Mono<Response<Boolean>> deleteFileIfExistsWithResponse(String fileName, D
      * </pre>
      * <!-- end com.azure.storage.file.datalake.DataLakeFileSystemAsyncClient.createDirectory#String -->
      *
-     * @param directoryName Name of the directory to create. If the path name contains special characters, pass in the
-     * url encoded version of the path name.
+     * @param directoryName Name of the directory to create. Pass the name unencoded; the client percent-encodes it when
+     * building the request URL.
      * @return A {@link Mono} containing a {@link DataLakeDirectoryAsyncClient} used to interact with the directory
      * created.
      */
@@ -1243,8 +1243,8 @@ public Mono<DataLakeDirectoryAsyncClient> createDirectory(String directoryName)
      * </pre>
      * <!-- end com.azure.storage.file.datalake.DataLakeFileSystemAsyncClient.createDirectory#String-boolean -->
      *
-     * @param directoryName Name of the directory to create. If the path name contains special characters, pass in the
-     * url encoded version of the path name.
+     * @param directoryName Name of the directory to create. Pass the name unencoded; the client percent-encodes it when
+     * building the request URL.
      * @param overwrite Whether to overwrite, should a directory exist.
      * @return A {@link Mono} containing a {@link DataLakeDirectoryAsyncClient} used to interact with the directory
      * created.
@@ -1282,8 +1282,8 @@ public Mono<DataLakeDirectoryAsyncClient> createDirectory(String directoryName,
      * </pre>
      * <!-- end com.azure.storage.file.datalake.DataLakeFileSystemAsyncClient.createDirectoryWithResponse#String-String-String-PathHttpHeaders-Map-DataLakeRequestConditions -->
      *
-     * @param directoryName Name of the directory to create. If the path name contains special characters, pass in the
-     * url encoded version of the path name.
+     * @param directoryName Name of the directory to create. Pass the name unencoded; the client percent-encodes it when
+     * building the request URL.
      * @param permissions POSIX access permissions for the directory owner, the directory owning group, and others.
      * @param umask Restricts permissions of the directory to be created.
      * @param headers {@link PathHttpHeaders}
@@ -1347,8 +1347,8 @@ public Mono<Response<DataLakeDirectoryAsyncClient>> createDirectoryWithResponse(
      * </pre>
      * <!-- end com.azure.storage.file.datalake.DataLakeFileSystemAsyncClient.createDirectoryWithResponse#String-DataLakePathCreateOptions -->
      *
-     * @param directoryName Name of the directory to create. If the path name contains special characters, pass in the
-     * url encoded version of the path name.
+     * @param directoryName Name of the directory to create. Pass the name unencoded; the client percent-encodes it when
+     * building the request URL.
      * @param options {@link DataLakePathCreateOptions}
      * @return A {@link Mono} containing a {@link Response} whose {@link Response#getValue() value} contains a {@link
      * DataLakeDirectoryAsyncClient} used to interact with the directory created.
@@ -1378,8 +1378,8 @@ public Mono<Response<DataLakeDirectoryAsyncClient>> createDirectoryWithResponse(
      * </pre>
      * <!-- end com.azure.storage.file.datalake.DataLakeFileSystemAsyncClient.createDirectoryIfNotExists#String -->
      *
-     * @param directoryName Name of the directory to create. If the path name contains special characters, pass in the
-     * url encoded version of the path name.
+     * @param directoryName Name of the directory to create. Pass the name unencoded; the client percent-encodes it when
+     * building the request URL.
      * @return A {@link Mono} containing a {@link DataLakeDirectoryAsyncClient} used to interact with the directory
      * created.
      */
@@ -1418,8 +1418,8 @@ public Mono<DataLakeDirectoryAsyncClient> createDirectoryIfNotExists(String dire
      * </pre>
      * <!-- end com.azure.storage.file.datalake.DataLakeFileSystemAsyncClient.createDirectoryIfNotExistsWithResponse#String-DataLakePathCreateOptions -->
      *
-     * @param directoryName Name of the directory to create. If the path name contains special characters, pass in the
-     * url encoded version of the path name.
+     * @param directoryName Name of the directory to create. Pass the name unencoded; the client percent-encodes it when
+     * building the request URL.
      * @param options {@link DataLakePathCreateOptions}
      * @return A {@link Mono} containing a {@link Response} whose {@link Response#getValue() value} contains a
      * {@link DataLakeDirectoryAsyncClient} used to interact with the directory created. If {@link Response}'s status
@@ -1459,8 +1459,8 @@ public Mono<Response<DataLakeDirectoryAsyncClient>> createDirectoryIfNotExistsWi
      * </pre>
      * <!-- end com.azure.storage.file.datalake.DataLakeFileSystemAsyncClient.deleteDirectory#String -->
      *
-     * @param directoryName Name of the directory to delete. If the path name contains special characters, pass in the
-     * url encoded version of the path name.
+     * @param directoryName Name of the directory to delete. Pass the name unencoded; the client percent-encodes it when
+     * building the request URL.
      * @return A reactive response signalling completion.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
@@ -1486,8 +1486,8 @@ public Mono<Void> deleteDirectory(String directoryName) {
      * </pre>
      * <!-- end com.azure.storage.file.datalake.DataLakeFileSystemAsyncClient.deleteDirectoryWithResponse#String-boolean-DataLakeRequestConditions -->
      *
-     * @param directoryName Name of the directory to delete. If the path name contains special characters, pass in the
-     * url encoded version of the path name.
+     * @param directoryName Name of the directory to delete. Pass the name unencoded; the client percent-encodes it when
+     * building the request URL.
      * @param recursive Whether to delete all paths beneath the directory.
      * @param requestConditions {@link DataLakeRequestConditions}
      * @return A {@link Mono} containing status code and HTTP headers
@@ -1524,8 +1524,8 @@ public Mono<Response<Void>> deleteDirectoryWithResponse(String directoryName, bo
      * </pre>
      * <!-- end com.azure.storage.file.datalake.DataLakeFileSystemAsyncClient.deleteDirectoryIfExists#String -->
      *
-     * @param directoryName Name of the directory to delete. If the path name contains special characters, pass in the
-     * url encoded version of the path name.
+     * @param directoryName Name of the directory to delete. Pass the name unencoded; the client percent-encodes it when
+     * building the request URL.
      * @return a reactive response signaling completion. {@code true} indicates that the specified directory was
      * successfully deleted, {@code false} indicates that the specified directory did not exist.
      */
@@ -1560,8 +1560,8 @@ public Mono<Boolean> deleteDirectoryIfExists(String directoryName) {
      * </pre>
      * <!-- end com.azure.storage.file.datalake.DataLakeFileSystemAsyncClient.deleteDirectoryIfExistsWithResponse#String-DataLakePathDeleteOptions -->
      *
-     * @param directoryName Name of the directory to delete. If the path name contains special characters, pass in the
-     * url encoded version of the path name.
+     * @param directoryName Name of the directory to delete. Pass the name unencoded; the client percent-encodes it when
+     * building the request URL.
      * @param options {@link DataLakePathDeleteOptions}
      * @return A reactive response signaling completion. If {@link Response}'s status code is 200, the file was
      * successfully deleted. If status code is 404, the file does not exist.