: does not look like an OCI image layout (missing…

Error message

{}: does not look like an OCI image layout (missing index.json)

What it means

`mise oci run --image-dir <dir>` validates the directory is a valid OCI image layout by requiring index.json before locating a container engine. Argument validation is deliberately done first so bad --image-dir values surface before any engine-missing errors.

Solutions

Pass the OCI layout directory produced by `mise oci build` (the one containing index.json)
Rebuild the image with `mise oci build` if the layout was deleted
Verify with `test -f <dir>/index.json` before invoking mise oci run

Example fix

// before
mise oci run --image-dir ./image.tar ...
// after
mise oci run --image-dir ./target/oci-image ...
# where ./target/oci-image/index.json exists

Defensive patterns

Strategy: validation

Validate before calling

test -f "$image_dir/index.json" || { echo "$image_dir is not an OCI layout"; exit 1; }

Prevention

Run mise oci build in the same session/machine as oci run, or persist the layout to a known dir
Pass directories (not .tar files) to --image-dir
Script the build->run handoff so the layout path is passed explicitly

When it happens

Trigger: Running `mise oci run --image-dir <dir>` where <dir>/index.json is not a regular file — wrong directory, incomplete build output, or a deleted temp layout.

Common situations: Pointing --image-dir at the wrong path after a build, running from a different machine/tmpfs where the build's temp layout was cleaned up, or passing a tarball path instead of a directory.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at src/cli/oci/run.rs:117

    cmd: Vec<String>,
}

#[derive(Debug, Clone, Copy, PartialEq, usage_rs::ValueEnum)]
enum Engine {
    Auto,
    Podman,
    Docker,
}

impl Run {
    pub(super) async fn run(self) -> Result<()> {
        Settings::get().ensure_experimental("mise oci run")?;

        // 1. Validate arguments first so bad args win over "engine missing".
        if let Some(d) = &self.image_dir
            && !d.join("index.json").is_file()
        {
            bail!(
                "{}: does not look like an OCI image layout (missing index.json)",
                d.display()
            );
        }

        // 2. Locate a container engine.
        let engine = select_engine(self.engine)?;

        // 3. Build (or reuse an existing layout). When building, keep the
        // `TempDir` alive for the duration of the command — it removes the
        // directory on drop, so partial-gigabyte tool layers don't pile up
        // in /tmp across invocations.
        let (image_dir, _tempdir_guard): (PathBuf, Option<TempDir>) =
            if let Some(d) = &self.image_dir {
                (d.clone(), None)
            } else {
                let td = TempDir::with_prefix("mise-oci-run-")
                    .wrap_err("creating temp dir for oci build output")?;

View on GitHub (pinned to 533346cc37)