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

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:

Decompress the response correctly without error, OR
Provide a flag (e.g., --no-compression or AZURE_CLI_DISABLE_COMPRESSION=1) to
request uncompressed responses by sending Accept-Encoding: identity, OR
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

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

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:

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

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

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

az storage fs file download fails with a zlib.error: Error -3 while decompressing data /
urllib3.exceptions.DecodeError when downloading certain files from an ADLS Gen2
(HNS-enabled) filesystem. The server responds with Content-Encoding: deflate, but the
response body is not actually deflate-compressed (or is malformed), so the standard
urllib3/requests transparent decompression fails. Other files in the same container
download fine, suggesting the storage service (or a proxy in front of it) is
inconsistently/incorrectly setting the Content-Encoding: deflate header for some blob
paths (e.g. those with special characters or under certain HNS paths), while the actual
bytes are not compressed.

Repro:

az storage fs file download \
  --file-system '<fs>' \
  --path 'testdata/special_character_test/<file>' \
  -d '<dest>' \
  --account-name <account> --account-key <key>

Error observed:

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

Reported on azure-cli 2.75.0 and 2.86.0, Python 3.11/3.12, against ADLS Gen2 (HNS-enabled)
storage accounts using --account-key auth.

🛠️ Suggested fix directions

In the storage data-plane download path (azure.cli.command_modules.storage, likely
using the azure-storage-file-datalake / azure-storage-blob SDK's download/transport
layer), send Accept-Encoding: identity for file download requests to avoid the service
applying (or mis-declaring) content-encoding, since blob/ADLS file content should not be
transparently transport-compressed.
Alternatively, catch the decode error, retry once without Accept-Encoding: gzip, deflate
(i.e. identity), and re-download.
Ensure the fix is scoped to the storage file/fs download commands only, and add a unit
test simulating a response with a bogus/mismatched Content-Encoding: deflate header to
confirm the retry/identity-encoding path is exercised.

Use this EXACT PR title: [Storage] Fix #33469: az storage fs file download: Handle content-encoding deflate decode errors on ADLS Gen2 downloads

PR title & description format (required)

This repo enforces a PR format (guide). Please author the PR exactly as follows or CI's Check the Format of Pull Request Title and Content will fail.

Use this EXACT PR title (copy verbatim, do not reword):

[Storage] Fix #33469: `az storage fs file download`: Handle content-encoding deflate decode errors on ADLS Gen2 downloads

Keep the backticks around the command and the Fix #33469: prefix. You may only adjust the wording after the command (the final summary) if the fix changes; the [Storage] prefix, issue link, and backticked command must stay.

Description — follow the PR template and fill in:

Link the issue — start the Description with a closing keyword so the PR auto-links and closes it: Fixes #33469.
Related command — the az ... command this affects.
Description (mandatory) — why the bug happens, what you changed, and the resulting behavior.
Testing Guide — example command(s) showing the fix works.
History Notes — leave the title to drive the history note, or add extra lines in the same format (component in brackets + the command in backticks), e.g. [Storage] `az <command>`: <note>.
Keep the template checklist and tick the items you've satisfied.

_{X Engineering Agent · Fixer · react 👍 / 👎 to train the agent}

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

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

Description

Describe the bug

Related command

Errors

Issue script & Debug output

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

Environment Summary

Additional context

Activity

yonzhan commented on May 28, 2026

github-actions commented on May 28, 2026

Solution 1:

Solution 2:

microsoft-github-policy-service commented on May 28, 2026

3 remaining items

microsoft-github-policy-service commented on Jul 15, 2026

x-engineering-agent commented on Jul 15, 2026

microsoft-github-policy-service commented on Sep 2, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions