Thanks to visit codestin.com
Credit goes to github.com

Skip to content

fix: skip unpacking symlinks on Windows instead of failing#2454

Open
pb01ka wants to merge 1 commit into
prefix-dev:mainfrom
pb01ka:win-symlink
Open

fix: skip unpacking symlinks on Windows instead of failing#2454
pb01ka wants to merge 1 commit into
prefix-dev:mainfrom
pb01ka:win-symlink

Conversation

@pb01ka
Copy link
Copy Markdown
Contributor

@pb01ka pb01ka commented Apr 28, 2026 •
edited
Loading

Problem

Refer - #940 (comment)

When rattler-build tries to extract a source archive (e.g. a .tar.gz) that contains symbolic links on Windows without Developer Mode enabled, the extraction fails hard with no actionable information:

 ╭─ Running build for recipe: podman-desktop-1.26.2-hf0b5a29_0
 │
 │ ╭─ Fetching source code
 │ │ Fetching source from url: https://github.com/podman-desktop/podman-desktop/archive/refs/tags/v1.26.2.tar.gz
 │ │ Downloading from: https://github.com/podman-desktop/podman-desktop/archive/refs/tags/v1.26.2.tar.gz
 │ │ ⚠ warning Failed to fetch from https://github.com/podman-desktop/podman-desktop/archive/refs/tags/v1.26.2.tar.gz: Failed to extract archive: Failed to extract tar
 │ │ ⚠ warning .gz: failed to unpack `\\?\C:\Users\Gagan\staged-recipes\build_artifacts\src_cache\.tmpyweool\podman-desktop-1.26.2\CLAUDE.md`
 │ │
 │ ╰─────────────────── (took 8 seconds)
 │
 ╰─────────────────── (took 8 seconds)
Error:   x Failed to extract archive: Failed to extract tar.gz: failed to unpack `\\?\C:\Users\Gagan\staged-recipes\build_artifacts\src_cache\.tmpyweool\podman-desktop-
  | 1.26.2\CLAUDE.md`

Solution

Instead of failing the entire extraction when a symlink cannot be created, this PR iterates tar entries manually and skips failing symlink entries with a warning on Windows. The approach mirrors what rattler/pixi already do for their own extraction path.

  1. unpack_tar_entries helper - replaces the single archive.unpack(target) call across all compression formats (.tar.gz, .tar.bz2, .tar.xz, .tar.zst, plain .tar) with a manual entry loop. On Windows, if unpacking a symlink entry fails, a tracing::warn! is emitted and extraction continues. Any other error still propagates as before.

  2. No registry access or new dependencies - no winreg, no windows-sys, no unsafe. The fix is pure platform-conditional Rust.

  3. Test coverage - a Windows-only test (test_symlink_extraction_skipped_on_windows) creates a minimal .tar.gz with a symlink entry and asserts that extract_tar succeeds regardless of Developer Mode status.

Notes

  • No behaviour change on Linux/macOS - the #[cfg(target_os = "windows")] block is a no-op on other platforms and all other errors still fail extraction.
  • A missing symlink will only surface as a build error if the symlink is actually needed, giving users a much clearer failure point.

@pb01ka pb01ka changed the title Hint users to enable Developer Mode on Windows symlink extraction failure fix: hint users to enable Developer Mode on Windows symlink extraction failure Apr 28, 2026
@pb01ka pb01ka marked this pull request as draft April 28, 2026 20:04
@pb01ka pb01ka marked this pull request as ready for review April 28, 2026 20:29
@pb01ka pb01ka mentioned this pull request Apr 28, 2026
Closed
@pb01ka pb01ka marked this pull request as draft April 29, 2026 10:47
@pb01ka pb01ka marked this pull request as ready for review April 29, 2026 13:33
baszalmstra
baszalmstra reviewed May 7, 2026
View reviewed changes
Comment thread crates/rattler_build_source_cache/src/cache.rs Outdated
@baszalmstra
Copy link
Copy Markdown
Contributor

baszalmstra commented May 7, 2026

Having a clear error is nice, but maybe even just continuing would be even nicer.

In rattler/pixi we try to unpack symlinks, and if they fail, we simply ignore them and issue a warning. I think that behavior would also be fine here. If it's a problem that they are missing, you will find out soon enough during the build itself.

Another option that we could pursue instead is to create a symlink, and if that fails, we simply materialize/create a copy of the file.

@pb01ka
Copy link
Copy Markdown
Contributor Author

pb01ka commented May 8, 2026

@baszalmstra I think both alternatives are better UX than a hard failure.

  1. Warn and skip

In rattler/pixi we try to unpack symlinks, and if they fail, we simply ignore them and issue a warning. I think that behavior would also be fine here. If it's a problem that they are missing, you will find out soon enough during the build itself.

It is simpler to implement - the tar crate surfaces individual entry errors, so we could iterate entries manually instead of calling unpack(), and skip symlink entries that fail. The downside is the extracted tree is incomplete, which may cause silent build failures later.

  1. Fall back to copying the target file

Another option that we could pursue instead is to create a symlink, and if that fails, we simply materialize/create a copy of the file.

This approach is more robust - if the symlink target exists in the archive, we can materialise it as a regular file. The extracted tree is functionally complete even without actual symlinks.

I'd lean towards the copy fallback since it's transparent to the build, but it does require iterating tar entries manually and tracking regular files as they're extracted so we can copy them when a symlink to them is encountered. Happy to implement whichever approach you prefer.

@pb01ka pb01ka mentioned this pull request May 11, 2026
Open
@pb01ka
Copy link
Copy Markdown
Contributor Author

pb01ka commented May 13, 2026

@baszalmstra Looking forward to your thoughts/opinions on my ideas above.

Thank you. <3.

@pb01ka
Copy link
Copy Markdown
Contributor Author

pb01ka commented May 15, 2026

Hi @baszalmstra. Waiting for your response. Thank you.

@pb01ka pb01ka mentioned this pull request May 17, 2026
Open
@baszalmstra
Copy link
Copy Markdown
Contributor

baszalmstra commented Jun 4, 2026

I like the copy fallback the most as well but it might be slightly tricky if there are symlinks to files that do not (yet) exist, because the order of extraction now matters. Id say we go with warn and skip first.

@baszalmstra
Copy link
Copy Markdown
Contributor

baszalmstra commented Jun 4, 2026

See this part in rattler where we implement this behavior for extraction:

https://github.com/conda/rattler/blob/f89ba4a5741af11e94547c8d6f0808ac2f8cb31c/crates/rattler_package_streaming/src/tokio/shared.rs#L18

@pb01ka
fix: skip unpacking symlinks on Windows instead of failing
bf89b09 
On Windows, creating symlinks requires Developer Mode or administrator
privileges. Rather than failing the entire extraction when a symlink
entry cannot be unpacked, iterate tar entries manually and skip failing
symlinks with a warning. The rest of the archive is extracted normally;
any missing symlink will surface as a build error only if it is actually
needed.
@pb01ka
Copy link
Copy Markdown
Contributor Author

pb01ka commented Jun 4, 2026

@baszalmstra I have implemented the warn and skip approach. Please take a look whenever you get a chance. Thank you.

@pb01ka pb01ka changed the title fix: hint users to enable Developer Mode on Windows symlink extraction failure fix: skip unpacking symlinks on Windows instead of failing Jun 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@baszalmstra baszalmstra baszalmstra left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@pb01ka @baszalmstra