jdx/mise · error · eyre::Report

mise oci needs `dpkg` on PATH to install apt system packages

Error message

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

What it means

The apt path needs dpkg in addition to apt-get: mise uses dpkg tooling (database/deb handling) to record and diff what apt-get installed into the temp rootfs. A host with apt-get but without dpkg is unusual (deliberately stripped images), and the guard fails fast rather than erroring mid-install.

Source

Thrown at src/oci/packages.rs:153

            }
            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"
                );
            }
        }
    }
    Ok(())
}

fn prepare_and_snapshot(
    manager: OciPackageManager,
    rootfs: &Path,
) -> Result<BTreeMap<PathBuf, FsEntry>> {
    match manager {
        OciPackageManager::Apk => prepare_apk_install(rootfs)?,
        OciPackageManager::Apt => prepare_apt_install(rootfs)?,
    }
    snapshot(rootfs)
}

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

Install dpkg on the build host (apt-get install dpkg, or use a standard debian/ubuntu image).
Fix PATH so /usr/bin is present and `command -v dpkg` resolves.
If dpkg genuinely cannot exist on the host, build the debian image from a debian-based CI container instead.

Example fix

# before
mise oci build   # dpkg missing

# after
apt-get install -y dpkg && mise oci build

Defensive patterns

Strategy: validation

Validate before calling

import shutil, sys
if apt_entries(config) and shutil.which("dpkg") is None:
    sys.exit("apt layer builds need dpkg on PATH; install it or use a standard debian host")

Prevention

Install dpkg on stripped debian-based build images rather than removing it for size.
Ensure PATH includes /usr/bin so dpkg resolves in CI shells.
Preflight both apt-get and dpkg — mise requires the pair for apt layers.

When it happens

Trigger: mise oci build with apt packages where file::which("dpkg") is None — e.g. a debian-slim derivative that removed dpkg, a nix/conda-provided apt-get shim without dpkg, or PATH breakage hiding /usr/bin/dpkg.

Common situations: Minimal custom CI images; PATH pollution from conda/nix shims; containers where dpkg was uninstalled to save space.

Related errors

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