mise oci needs `apk` on PATH to install apk system packages…

Error message

mise oci needs `apk` on PATH to install apk system packages into the image

What it means

mise installs apk packages into the image by invoking the host's `apk` binary against the image filesystem. If `apk` is not on PATH, the installation cannot proceed and mise fails with this error. Host OS (Linux) is validated first; this is the second check.

Solutions

Install apk-tools on the host (`apt-get install apk-tools` on Debian/Ubuntu, or the equivalent package)
Fix PATH so the `apk` binary is visible to mise (check PATH under sudo/CI)
Run the build inside an Alpine-based container where apk is present

Defensive patterns

Strategy: validation

Validate before calling

command -v apk >/dev/null || echo "apk not on PATH; install apk-tools before building"

Try / catch

match build() {
    Err(e) if e.to_string().contains("needs `apk` on PATH") => {
        eprintln!("install apk-tools or run the build in an Alpine container");
    }
    r => r,
}

Prevention

Preinstall required package-manager binaries in CI images
Sanity-check PATH in build scripts (command -v apk)
Prefer running Alpine builds inside Alpine containers
Pin build-environment docs listing required host binaries

When it happens

Trigger: Running `mise oci build` with `[bootstrap.packages] apk = [...]` on a Linux host where `apk` (e.g. from alpine's apk-tools) is not installed or not on PATH.

Common situations: Building an Alpine-based image on a Debian/Ubuntu host that lacks apk-tools; minimal CI containers without apk; PATH stripped by sudo or the CI environment.

Related errors

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

Appendix: source

Thrown at src/oci/packages.rs:137

            .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() {
                bail!(
                    "mise oci needs `dpkg` on PATH to install apt system packages into the image"
                );

View on GitHub (pinned to 533346cc37)