jdx/mise · error · eyre::Report

mise oci requires an {}-based base image when [bootstrap.pac

Error message

mise oci requires an {}-based base image when [bootstrap.packages] contains {} entries; `scratch` has no {} metadata

What it means

When [bootstrap.packages] has entries, mise unpacks the base image and drives the matching host package manager (apk or apt) against that rootfs, so the base must actually be Alpine (apk) or Debian/Ubuntu (apt). With base_layers empty (a scratch base) there is no package-manager metadata to bootstrap from, and mise refuses instead of producing an image whose packages silently fail.

Source

Thrown at src/oci/packages.rs:73

    fn name(self) -> &'static str {
        match self {
            Self::Apk => "apk",
            Self::Apt => "apt",
        }
    }
}

pub fn build_system_packages_layer(
    layout: &ImageLayout,
    base_layers: &[Descriptor],
    managers: &[ManagerPackages],
    architecture: &str,
) -> Result<Option<SystemPackagesLayer>> {
    let Some((manager, requests)) = collect_package_requests(managers)? else {
        return Ok(None);
    };
    if base_layers.is_empty() {
        bail!(
            "mise oci requires an {}-based base image when [bootstrap.packages] contains {} \
             entries; `scratch` has no {} metadata",
            manager.name(),
            manager.name(),
            manager.name(),
        );
    }
    validate_host_requirements(manager)?;

    let td = TempDir::with_prefix(format!("mise-oci-{}-rootfs-", manager.name())).wrap_err_with(
        || {
            format!(
                "creating temp rootfs for {} system packages",
                manager.name()
            )
        },
    )?;
    let rootfs = td.path().join("rootfs");

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

Use a matching base image: alpine:3.20 for apk packages, debian:bookworm-slim / ubuntu:24.04 for apt packages.
Or drop [bootstrap.packages] and install nothing beyond mise-managed tools.
Verify the manager and base agree — apk entries on a debian base (or apt entries on alpine) are the adjacent mistake to check.

Example fix

# before
[bootstrap]
base = "scratch"
  [bootstrap.packages]
  curl = '*'

# after
[bootstrap]
base = "alpine:3.20"
  [bootstrap.packages]
  curl = '*'

Defensive patterns

Strategy: validation

Validate before calling

import sys
base = config["bootstrap"]["base"]
pkgs = config["bootstrap"].get("packages", {})
if pkgs and (base is None or base == "scratch"):
    sys.exit("[bootstrap.packages] requires an alpine (apk) or debian (apt) base image")

Prevention

Pair package families with their distro: apk -> alpine:*, apt -> debian/ubuntu.
Keep a matrix check in CI that validates base + packages combinations per mise.toml.
If image size drove you to scratch, use the distro -slim variants instead of dropping the base.

When it happens

Trigger: mise oci build with base = "scratch" (or no base) combined with any [bootstrap.packages] entry; collect_package_requests found apk or apt requests but the base image contributed zero layers.

Common situations: Starting from a scratch/minimal image to shrink size, then adding packages; setting a distroless/empty base without realizing packages need an OS rootfs.

Related errors

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