jdx/mise · error · eyre::Report

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

Error message

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

What it means

For apk packages, mise runs the host's apk binary in a chroot against the unpacked image rootfs — there is no container engine. apk only exists/runs meaningfully on Linux, so building an apk-packages image from macOS or Windows is rejected up front by validate_host_requirements.

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

Solutions

Run the build on a Linux host or CI runner (GitHub Actions ubuntu-latest, a linux container with docker).
On macOS, delegate to a remote builder or cross-build inside a devcontainer with docker.
Or remove the apk entries so the packages layer is skipped.

Example fix

# before (on macOS)
mise oci build

# after (inside linux CI or devcontainer)
mise oci build

Defensive patterns

Strategy: validation

Validate before calling

import platform, sys
uses_apk = any_apk_entries(config)
if uses_apk and platform.system() != "Linux":
    sys.exit("apk packages require a Linux build host; run in CI or a linux container")

Prevention

Move image builds to Linux CI; keep macOS workstations for dev only.
In a devcontainer/Docker Desktop setup, run mise oci build inside the linux VM/container.
Document the host requirement next to [bootstrap.packages] in the repo's mise docs.

When it happens

Trigger: mise oci build on macOS or Windows with [bootstrap.packages] containing apk entries (or an alpine base whose packages resolve to apk).

Common situations: Developing on a Mac and building images locally instead of in CI; the docs/quickstart alpine example run from a non-Linux workstation.

Related errors

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