jdx/mise · error · eyre::Report

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

After installing packages, mise diffs the rootfs snapshot and re-materializes changed entries into the new layer directory. Symlinks in that diff (very common from apk/apt alternatives and busybox links) can only be recreated with unix symlink(2); on a non-unix host (Windows) there is no equivalent, so any symlink in the diff aborts the build.

Source

Thrown at src/oci/packages.rs:749

    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 9dcfcaa0dc)

Solutions

1. Run the oci build in WSL2 or a Linux CI container — that is the supported environment for system-package layers
2. Alternatively use a base image that already contains the packages, so no [bootstrap.packages] diff is needed on Windows
3. Avoid packages known to create alternatives symlinks if you must build on Windows without system packages

// Before enabling [bootstrap.packages] on this host, require unix:
if cfg!(not(unix)) {
    eprintln!("oci system-package layers need a unix host (run in WSL2/Linux CI)");
    // skip the packages table or abort before `mise oci build`
}

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

When it happens

Trigger: Running `mise oci build` with `[bootstrap.packages]` entries on Windows, where the installed packages create at least one symlink in the filesystem diff (e.g. /usr/bin/vi → busybox, alternatives links like /etc/alternatives/editor).

Common situations: Developers on Windows workstations building OCI images with system packages; the apk path already hard-requires a Linux host, so this typically fires via the apt path on Windows.

Related errors

• remote cache symlink target is unsafe
• install from exe
• --localized-dir {raw:?} cannot be carried to Windows: {bad:?
• cannot write task stub because {} is a symbolic link
• cannot write Windows launcher because {} is not a generated

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