az storage fs file download fails with content-encoding: deflate decode error on ADLS Gen2

[Samarth-Tyagi]

Describe the bug

az storage fs file download consistently fails with deflate decompression errors when downloading files from ADLS Gen2 (HNS-enabled) storage accounts. The same files can be listed, uploaded, and their properties queried successfully- only file download triggers the error. The issue reproduces across multiple az CLI versions, Python versions, and Docker versions.

this fails for all types of files when we try to download them:
testdata/DIRvvnSCGPhR408/.../FILELCi6I8m and testdata/DIRvvnSCGPhR408/.../FILEU9yl8Eb and 'testdata/special_character_test/ファイル_japanese_日本語.txt'

Related command

docker exec azurecli az storage fs file download
--file-system 'vrts-adlsgen2-bptls-lr88-023'
--path 'testdata/special_character_test/ファイル_japanese_日本語.txt'
-d '/hoFxZx6ioNFz'
--account-name --account-key

Errors

ERROR: ('Received response with content-encoding: deflate, but failed to decode it.',
error('Error -3 while decompressing data: invalid stored block lengths'))

Error -3 while decompressing data: invalid block type
Error -3 while decompressing data: invalid distance too far back
Error -3 while decompressing data: invalid code lengths set
Error -3 while decompressing data: incorrect header check

Issue script & Debug output

docker exec azurecli az storage fs file download
--file-system 'vrts-adlsgen2-bptls-lr88-023'
--path 'testdata/special_character_test/ファイル_japanese_日本語.txt'
-d '/tmp/test_download'
--account-name
--account-key
--debug

Debug output:

cli.azure.cli.core.util: Request headers:

'User-Agent': 'python/3.12.9 (Linux) AZURECLI/2.86.0'

'Accept-Encoding': 'gzip, deflate'

'Accept': '/'

'Connection': 'keep-alive'

'x-ms-client-request-id': ''

'CommandName': 'storage fs file download'

'ParameterSetName': '--file-system --path -d --account-name --account-key --debug'

ERROR: ('Received response with content-encoding: deflate, but failed to decode it.',

error('Error -3 while decompressing data: invalid stored block lengths'))

Traceback (most recent call last):

... urllib3/response.py ... in _decoder.decompress(data)

zlib.error: Error -3 while decompressing data: invalid stored block lengths

The above exception was the direct cause of the following exception:

urllib3.exceptions.DecodeError: ('Received response with content-encoding: deflate,

but failed to decode it.', error('Error -3 while decompressing data: invalid stored block lengths'))

Environment:

azure-cli 2.86.0

core 2.86.0

Python location '/usr/bin/python3.12'

Python (Linux) 3.12.9 (main, Mar 26 2026, 23:21:55) [GCC 13.2.0]

Container: mcr.microsoft.com/azure-cli:2.86.0

Host: RHEL 8.8, Docker CE 26.1.3

NOTE: The same command works for other files in the same container.

For example, this succeeds:

docker exec azurecli az storage fs file download \

--file-system 'vrts-adlsgen2-bptls-lr88-023' \

--path 'testdata/0/000/000/006.txt' \

-d '/tmp/test_ok' \

--account-name --account-key

Exit Value: 0 (success)

Expected behavior

az storage fs file download should successfully download any file from an ADLS Gen2
filesystem regardless of the server's Content-Encoding response header.
When the server responds with Content-Encoding: deflate, the SDK should either:

1. Decompress the response correctly without error, OR
2. Provide a flag (e.g., --no-compression or AZURE_CLI_DISABLE_COMPRESSION=1) to
   request uncompressed responses by sending Accept-Encoding: identity, OR
3. Automatically retry with Accept-Encoding: identity when a deflate decode error
   is encountered.
   Currently, specific files fail consistently with 'Error -3 while decompressing data'
   on every attempt, while other files in the same container download successfully.
   The file content itself is not compressed — the Content-Encoding: deflate is applied
   by the HTTP transport layer, and the Python zlib decoder fails to parse it.

Environment Summary

Azure CLI version - tried on both 2.75.0 and 2.86.0
Python version - Python 3.11 and Python 3.12.9
Docker - 17.12.0-ce, 26.1.3
Container image - mcr.microsoft.com/azure-cli:2.75.0, mcr.microsoft.com/azure-cli:2.86.0
Storage account - ADLS Gen2 with HNS enabled
Auth Method - --account-name + --account-key (shared key)

azure-cli 2.86.0

core 2.86.0
telemetry 1.1.0

Dependencies:
msal 1.35.1
azure-mgmt-resource 24.0.0

Python location '/usr/bin/python3.12'
Config directory '/root/.azure'
Extensions directory '/root/.azure/cliextensions'

Python (Linux) 3.12.9 (main, Mar 26 2026, 23:21:55) [GCC 13.2.0]

Legal docs and information: aka.ms/AzureCliLegal

Your CLI is up-to-date.

Additional context

No response

[yonzhan]

Thank you for opening this issue, we will look into it.

[github-actions]

Here are some similar issues that might help you. Please check if they can solve your problem.

• Azure storage blob not able to download files #8245

---

Possible solution (Extracted from existing issue, might be incorrect; please verify carefully)

Solution 1:

This is a known issue. There is a workaround, but it hasn't been integrated into the SDK yet. The issue is being tracked for inclusion in the next generation of the Storage SDK.

Reference:

• Azure storage blob not able to download files #8245 (comment)
• Azure storage blob not able to download files #8245 (comment)

Solution 2:

To summarize, having the content settings: "contentEncoding": "gzip" and ContentType: application/tar+gzip blocks get_blob_to_path from properly downloading a blob. A potential workaround is to manually remove these content settings from the file properties before attempting the download.

Reference:

• Azure storage blob not able to download files #8245 (comment)

Powered by issue-sentinel

[microsoft-github-policy-service]

🔔 Routing this issue to @act-codegen-extensibility-squad.