mise oci needs a Linux host to install apk system packages…

Error message

mise oci needs a Linux host to install apk system packages into an image

What it means

Installing apk packages into an image is done on the host by invoking apk against the image root filesystem (chroot-style). apk tooling only works on Linux, so mise validates the host OS first and refuses with this error when building on macOS, Windows, or other non-Linux systems.

Solutions

Run the build on a Linux machine or Linux CI runner
Use a Linux container/Docker to host the build (build inside `docker run --platform linux`)
Switch to a package manager that doesn't require a Linux host, or drop the apk packages

Defensive patterns

Strategy: validation

Validate before calling

# before running the build
[ "$(uname -s)" = "Linux" ] || echo "apk package installs require a Linux host"

Try / catch

match build() {
    Err(e) if e.to_string().contains("needs a Linux host") => {
        eprintln!("rerun inside a Linux container or on a Linux CI runner");
    }
    r => r,
}

Prevention

Run oci image builds on Linux runners in CI
Wrap builds in a Linux container on developer machines
Keep platform-dependent steps out of shared build scripts
Document host requirements next to the bootstrap config

When it happens

Trigger: Running `mise oci build` with `[bootstrap.packages] apk = [...]` on a non-Linux host, causing `validate_host_requirements` (via `build_system_packages_layer`) to check `std::env::consts::OS != "linux"`.

Common situations: Developer building an Alpine-based image on a macOS laptop; CI runner on Windows; container-in-container where the host is not Linux.

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

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

Appendix: source

Thrown at src/oci/packages.rs:134

        "oci: adding {} system packages: {}",
        manager.name(),
        requests
            .iter()
            .map(ToString::to_string)
            .collect::<Vec<_>>()
            .join(", ")
    );
    Ok(Some(SystemPackagesLayer {
        blob: layer::build_layer_from_dir_preserve_metadata(&diff_dir, "")?,
        manager: manager.name(),
    }))
}

fn validate_host_requirements(manager: OciPackageManager) -> Result<()> {
    match manager {
        OciPackageManager::Apk => {
            if std::env::consts::OS != "linux" {
                bail!("mise oci needs a Linux host to install apk system packages into an image");
            }
            if file::which("apk").is_none() {
                bail!("mise oci needs `apk` on PATH to install apk system packages into the image");
            }
            if !crate::system::sudo::is_root() {
                bail!(
                    "mise oci needs to run as root to install apk system packages because apk \
                     executes package scripts in a chroot"
                );
            }
        }
        OciPackageManager::Apt => {
            if file::which("apt-get").is_none() {
                bail!(
                    "mise oci needs `apt-get` on PATH to install apt system packages into the image"
                );
            }
            if file::which("dpkg").is_none() {

View on GitHub (pinned to 533346cc37)