Offline Installer Mismatch: Website provides `.tgz` archive, but installer expects `.zst` (EIM-329)

[eMUQI]

Checklist

• Checked the issue tracker for similar issues to ensure this is not a duplicate
• Read the documentation to confirm the issue is not addressed there and your configuration is set correctly
• Tested with the latest version to ensure the issue hasn't been fixed

How often does this bug occurs?

always

Expected behavior

Download the offline installer from the https://dl.espressif.cn/dl/eim/?tab=offline page, and be able to complete the installation using the downloaded offline installer and accompanying archive files

Actual behavior (suspected bug)

On the offline installer download page (https://dl.espressif.cn/dl/eim/?tab=offline), the instructions state:

⚠️ Warning: Offline installer files are large (3-4GB). Due to browser memory limitations, you will receive separate installer and archive files to use together.

I got the two provided files:

• eim-gui-windows-x64.exe
• archive_v5.5.1_windows-x64.tgz

However, when I run the eim-gui-windows-x64.exe installer and attempt an offline installation, the application prompts for an archive file with a **.zst** extension.

This creates a mismatch, as the downloaded archive is in .tgz format, not .zst, preventing the offline installation from being completed.

Error logs or terminal output

Steps to reproduce the behavior

1. Go to the Espressif Download Mirror: https://dl.espressif.cn/dl/eim
2. Select the "Offline installer" tab.
3. Click the "Download" button for the default version (v5.5.1).
4. This downloads two files: eim-gui-windows-x64.exe and archive_v5.5.1_windows-x64.tgz.
5. Run the eim-gui-windows-x64.exe installer and choose the offline installation option.
6. When prompted to provide the archive file, observe that the installer is specifically looking for a .zst file.
7. Unable to proceed because the provided archive_v5.5.1_windows-x64.tgz file is not in the expected format.

Project release version

v0.5.5

System architecture

Intel/AMD 64-bit (modern PC, older Mac)

Operating system

Windows

Operating system version

Windows 11

Shell

other (details in Additional context)

Additional context

To resolve this issue, there are two potential solutions:

1. Modify the offline installer to be compatible with .tgz archive files.
2. Change the download link on the website to provide the archive in the .zst format that the installer expects.

The second option (providing a .zst file directly) is recommended as it would be the most straightforward and least confusing for end-users.

[eMUQI]

I'd like to provide an update with some additional information.

It appears the type of archive file served by the download server is dependent on the browser being used.

• Chrome (141.0.7390.108): Downloads the .tgz file.
• Firefox (144.0): Downloads the expected .zst file.

[Hahihula]

just tested on Chrome 141.0.7390.108
and got zst archive for both windows and macos ...
all the avalible archives are listed in json file https://dl.espressif.cn/dl/eim/offline_archives.json
there is no tgz archive in the S3 bucket:

PRE apt/
2024-12-06 17:42:21          0 
2025-10-15 22:18:03 3360410687 archive_v5.1.6_linux-aarch64.zst
2025-10-15 22:19:00 3392056486 archive_v5.1.6_linux-x64.zst
2025-10-16 00:25:42 3168703963 archive_v5.1.6_macos-aarch64.zst
2025-10-16 00:24:45 3260628428 archive_v5.1.6_macos-x64.zst
2025-10-15 22:30:01 3860849000 archive_v5.1.6_windows-x64.zst
2025-10-15 22:17:30 3409610938 archive_v5.2.6_linux-aarch64.zst
2025-10-15 22:18:31 3425492724 archive_v5.2.6_linux-x64.zst
2025-10-16 00:20:35 3317513361 archive_v5.2.6_macos-aarch64.zst
2025-10-15 23:36:53 3375760702 archive_v5.2.6_macos-x64.zst
2025-10-15 22:29:28 3768763607 archive_v5.2.6_windows-x64.zst
2025-10-15 22:17:44 3587446588 archive_v5.3.4_linux-aarch64.zst
2025-10-15 22:19:25 3608477026 archive_v5.3.4_linux-x64.zst
2025-10-15 23:52:09 3497192285 archive_v5.3.4_macos-aarch64.zst
2025-10-15 23:56:23 3559688771 archive_v5.3.4_macos-x64.zst
2025-10-15 22:34:12 3788262668 archive_v5.3.4_windows-x64.zst
2025-10-15 22:17:34 3878473045 archive_v5.4.2_linux-aarch64.zst
2025-10-15 22:19:36 3908318829 archive_v5.4.2_linux-x64.zst
2025-10-15 22:57:37 3796411004 archive_v5.4.2_macos-aarch64.zst
2025-10-15 23:02:40 3866202405 archive_v5.4.2_macos-x64.zst
2025-10-15 22:28:42 4374845321 archive_v5.4.2_windows-x64.zst
2025-10-24 17:37:53 3902580145 archive_v5.4.3_linux-aarch64.zst
2025-10-24 17:38:12 3957205244 archive_v5.4.3_linux-x64.zst
2025-10-24 17:43:40 3823443002 archive_v5.4.3_macos-aarch64.zst
2025-10-24 18:08:47 3894033778 archive_v5.4.3_macos-x64.zst
2025-10-24 17:45:47 4427432404 archive_v5.4.3_windows-x64.zst
2025-10-15 22:17:44 3977294269 archive_v5.5.1_linux-aarch64.zst
2025-10-15 22:20:21 4024434774 archive_v5.5.1_linux-x64.zst
2025-10-15 23:41:27 3868779480 archive_v5.5.1_macos-aarch64.zst
2025-10-15 23:49:16 3960599449 archive_v5.5.1_macos-x64.zst
2025-10-15 22:30:59 4484142197 archive_v5.5.1_windows-x64.zst
2025-02-19 10:58:28      11963 eim_cli_release.json
2025-02-13 21:24:40      10524 eim_gui_release.json
2025-10-15 21:51:32      46710 eim_unified_release.json
2025-10-15 21:03:24      39816 index.html
2025-10-24 18:10:15       4143 offline_archives.json

I can't imagine how you could get tgz archive with anything in it.
In the past we experimented with zip archives, but never with tgz for Windows platform.

If your troubles persist, you can use the direct link https://dl.espressif.cn/dl/eim/archive_v5.5.1_windows-x64.zst, which can be found in the table below the buttons and download the zst archive separately.

[eMUQI]

_2025_10_29_11_11_53_965.mp4

[eMUQI]

Directly access https://dl.espressif.cn/dl/eim/archive_v5.5.1_windows-x64.zst

_2025_10_29_11_16_05_113.mp4

[eMUQI]

I can't imagine how you could get tgz archive with anything in it.

Multiple colleagues on our team have reproduced this issue.

Some possible explanations from GPT5: https://poe.com/s/qIebvgcl6km6goTdxVow

[Hahihula]

Ok, we reproduced this issue. But it seems like it's happening only from inside China and only for windows zst archive. We are looking into it and hopefully we will find what's causing this.

[eMUQI]

Hi @Hahihula,

Thanks for confirming the issue and looking into it. It's been about a month since your last update. I wanted to follow up to see if there's been any progress on this issue.

To recap the situation:

The problem seems to only affects users inside China when downloading Windows .zst archives

The offline installer download page continues to serve .tgz files instead of the expected .zst format

While the .zst files exist in the S3 bucket and can be accessed directly via the JSON manifest, the web interface doesn't serve them correctly

Since this issue has the tracking ID EIM-329, has there been any update on the backend team's investigation? Are there plans to:

Update the download server configuration to properly serve .zst files to all regions?

Or possibly add regional CDN/mirror support to handle the China-specific issue?

This continues to impact offline installations for users in China, so any update would be appreciated.

Thanks!

[Hahihula]

Hi @eMUQI ,

Thanks a lot for the detailed follow-up — I really appreciate the clear summary. You’re right that this issue has been open for a while, so thanks for the nudge.

To share the current status: the behavior you're seeing is unfortunately tied to how the China-region S3 mirror handles file types. The installation download page itself is a static S3-hosted site that simply serves direct links to the files. There’s no server-side logic or configuration layer we can adjust on our side — the browser downloads whatever the S3 mirror returns.

And as you correctly observed, this happens only on the CN S3 mirror, not on the original AWS S3 buckets outside China. Ironically, the suggestion to improve access via a CN mirror is also the root cause of the .tgz mis-serving behavior.

Workarounds currently available

Until the S3 mirror issue is addressed, users in China can install successfully using one of the following methods:

1. Rename the archive manually after download
   Chrome-based browsers incorrectly rewrite the .zst extension to .tgz. Renaming the file back to .zst fixes the problem.

2. Use a non-Chromium browser to download the archive
   Browsers like Safari or Firefox do not have this issue and correctly download the .zst file.

3. Download from the US-East S3 mirror
   The original bucket (non-China regions) serves the correct file type. Accessing it directly avoids the CN-mirror behavior entirely.

About backend progress

I’ll follow up with our infrastructure team again and make sure this stays visible on their side. If there’s any update on improving the CN mirroring or adjusting how file metadata is handled, I’ll report back here.

Thanks again for bringing this up — and for your patience while we work through the limitations of the China-region S3 environment. 🙏

[MichaelWu-ESP]

@eMUQI we are still debugging on this issue. During the meantime, you can directly download the zst file not click on Download button. Like below:

For example: wget https://dl.espressif.cn/dl/eim/archive_v5.5.1_windows-x64.zst
Or copy the url to safari or firefox browser directly: https://dl.espressif.cn/dl/eim/archive_v5.5.1_windows-x64.zst