jdx/mise · error

OCI system package layers with symlinks require a unix host

Error message

OCI system package layers with symlinks require a unix host

What it means

This error is thrown when materializing an OCI image layer that contains a symbolic link on a non-Unix host (e.g. Windows). The copy path only implements symlink creation via the Unix-only `std::os::unix::fs::symlink` call, so on other platforms it aborts rather than silently producing a wrong filesystem entry.

Solutions

1. Run this operation on a Linux/macOS host or in a Unix-based container (e.g. WSL2 on Windows).
2. Rebuild or pick an image variant whose layers contain no symlinks if you must stay on Windows.
3. Add Windows support by materializing symlinks as copies, hardlinks, or Windows reparse points before reaching copy_entry.

Example fix

// before (non-unix host)
bail!("OCI system package layers with symlinks require a unix host");
// after (fallback: copy the target's content instead of linking)
#[cfg(not(unix))]
{
    let meta = fs::metadata(&src)?;
    if meta.is_file() {
        fs::copy(&src, &dst)?;
    } else {
        bail!("OCI system package layers with symlinks require a unix host");
    }
}

if cfg!(not(unix)) {
    let has_symlinks = layer_contains_symlinks(&manifest); // scan entries for FsEntryKind::Symlink
    if has_symlinks {
        eprintln!("layer requires a unix host; switching to WSL/container");
    }
}

fn is_unix() -> bool { cfg!(unix) }

When it happens

Trigger: Calling the OCI package/system-package materialization flow (`materialize_diff` -> `copy_entry`) on a non-unix platform where a layer entry has `FsEntryKind::Symlink`.

Common situations: Running `mise oci` image pulls/builds that incorporate Linux system packages (apt/rpm layers full of symlinks like /usr/bin -> alternatives) on a Windows developer machine or Windows CI runner.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• brew import is not supported on windows
• . Creating directory symlinks on Windows may require…
• failed to create file symlink
• GitHub relay requires Linux or macOS
• managed system files are only supported on Unix

AI-assisted analysis of jdx/mise@533346cc37 (2026-09-17). Data as JSON: /api/errors/bc7bc1396edf3994. Report an issue: GitHub.

Appendix: source

Thrown at src/oci/packages.rs:784

    if let Some(parent) = dst.parent() {
        file::create_dir_all(parent)?;
    }
    match &entry.kind {
        FsEntryKind::Dir => {
            file::create_dir_all(&dst)?;
            set_mode(&dst, entry.mode)?;
        }
        FsEntryKind::File { .. } => {
            file::copy(&src, &dst)?;
            set_mode(&dst, entry.mode)?;
        }
        FsEntryKind::Symlink { target } => {
            #[cfg(unix)]
            symlink(target, &dst)?;
            #[cfg(not(unix))]
            {
                let _ = target;
                bail!("OCI system package layers with symlinks require a unix host");
            }
        }
        FsEntryKind::Other => {
            warn!(
                "oci: skipping unsupported filesystem entry {}",
                src.display()
            );
        }
    }
    Ok(())
}

fn set_mode(path: &Path, mode: u32) -> Result<()> {
    #[cfg(unix)]
    fs::set_permissions(path, fs::Permissions::from_mode(mode))?;
    #[cfg(not(unix))]
    {
        let _ = (path, mode);

View on GitHub (pinned to 533346cc37)