jdx/mise · error · eyre::Report

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

Even on Linux, apk-based packages require the actual apk binary on PATH because mise shells out to it to install into the image rootfs. Hosts that are not Alpine (Ubuntu, Fedora, Arch) have no apk, so the check fails before any rootfs work starts.

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

Solutions

Run the build from an Alpine environment (alpine container with docker mounted, or an alpine CI runner).
Switch packages to the apt manager and use a debian/ubuntu base when your build host is debian-based.
Or use a real container engine path (docker build) for system packages instead of mise's native layer.

Example fix

# before (ubuntu runner, alpine base)
[bootstrap]
base = "alpine:3.20"

# after (match manager to host)
[bootstrap]
base = "debian:bookworm-slim"   # host is ubuntu -> apt path works

Defensive patterns

Strategy: validation

Validate before calling

import shutil, sys
if apk_entries(config) and shutil.which("apk") is None:
    sys.exit("host has no apk; use an alpine builder or switch to apt/debian base")

Prevention

Match the build host distro to the base image distro (alpine host for alpine images).
Check `command -v apk` (and apt-get/dpkg for apt) as a CI preflight step.
Consider docker build for system packages when the host cannot match the image.

When it happens

Trigger: mise oci build on a non-Alpine Linux host (e.g. Ubuntu CI runner) with apk/[alpine-base] package entries; file::which("apk") returns None.

Common situations: ubuntu-latest GitHub runners used to build alpine images; a debian dev box; apk removed from an alpine dev container.

Related errors

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