jdx/mise · error

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

Error message

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

What it means

`mise oci run --image-dir <d>` requires `d` to be a valid OCI image layout (one containing `index.json` at its root, as produced by `mise oci build`). This check runs FIRST — before container-engine detection — deliberately so a bad argument wins over the 'engine missing' error and you get the most specific message.

Source

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

    cmd: Vec<String>,
}

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

impl Run {
    pub 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 9dcfcaa0dc)

Solutions

1. Generate the layout first: `mise oci build -o ./image ...` then `mise oci run --image-dir ./image ...`
2. Confirm the marker: `test -f ./out/index.json`
3. Re-extract the artifact if index.json was lost in transit

Example fix

# before
mise oci run --image-dir ./out -- bash
# after
mise oci build -o ./out && mise oci run --image-dir ./out -- bash

# bash: validate before oci run
if [ -n "$IMAGE_DIR" ] && [ ! -f "$IMAGE_DIR/index.json" ]; then
  echo "invalid OCI layout: $IMAGE_DIR" >&2; exit 2
fi
mise oci run ${IMAGE_DIR:+--image-dir "$IMAGE_DIR"} -- bash

When it happens

Trigger: `mise oci run --image-dir ./out ...` where ./out lacks index.json: empty directory, parent of the real layout, leftover partial output, or a path pointing at a tarball's containing folder instead of the extracted layout.

Common situations: Reusing a CI artifact directory whose layout files were stripped; passing the build's temp-dir root instead of its `image` subdirectory; typos in the path so a different (layout-less) directory is found.

Related errors

• {}: does not look like an OCI image layout (missing index.js
• {engine_bin} exited abnormally: {status:?}
• --engine podman requested but `podman` was not found on PATH
• --engine docker requested but `docker` was not found on PATH
• no supported container engine found. Install podman or docke

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