--engine podman requested but `podman` was not found on PATH

Error message

--engine podman requested but `podman` was not found on PATH

What it means

`--engine podman` explicitly demands podman. `select_engine` checks `file::which("podman")` and bails immediately rather than silently falling back to docker, because the user named the engine explicitly. Auto mode (no --engine) is the one that falls back.

Source

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

        let status = run_result?;
        if let Some(code) = status.code() {
            if code != 0 {
                return Err(crate::request_exit(code));
            }
        } else if !status.success() {
            bail!("{engine_bin} exited abnormally: {status:?}");
        }
        Ok(())
    }
}

fn select_engine(requested: Engine) -> Result<Engine> {
    match requested {
        Engine::Podman => {
            if file::which("podman").is_some() {
                Ok(Engine::Podman)
            } else {
                bail!("--engine podman requested but `podman` was not found on PATH")
            }
        }
        Engine::Docker => {
            if file::which("docker").is_none() {
                bail!("--engine docker requested but `docker` was not found on PATH");
            }
            Ok(Engine::Docker)
        }
        Engine::Auto => {
            if file::which("podman").is_some() {
                Ok(Engine::Podman)
            } else if file::which("docker").is_some() {
                Ok(Engine::Docker)
            } else {
                bail!("no supported container engine found. Install podman or docker.")
            }
        }
    }

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

Install podman (`brew install podman`, `apt install podman`, ...)
Omit `--engine` so Auto mode falls back to docker if that is what's available
Verify mise can see it: `command -v podman` in the same shell/env mise runs in

Example fix

# before
mise oci run --engine podman ghcr.io/you/devenv:tag -- bash
# after
mise oci run ghcr.io/you/devenv:tag -- bash   # auto-selects available engine

Defensive patterns

Strategy: validation

Validate before calling

# bash: require podman only when explicitly demanded
if [ "$ENGINE" = "podman" ] && ! command -v podman >/dev/null 2>&1; then
  echo "podman required but not on PATH" >&2; exit 2
fi
mise oci run ${ENGINE:+--engine "$ENGINE"} -- bash

Prevention

Omit --engine unless you truly need engine-specific behavior; Auto mode degrades gracefully
In Dockerfile/CI images, verify with `command -v podman` in a smoke-test step

When it happens

Trigger: `mise oci run --engine podman ...` on a machine without podman installed, or with podman installed but not on the PATH mise sees (flatpak-installed podman, ~/.local/bin not in PATH, PATH rewritten by mise env or a container).

Common situations: CI images that ship docker only; macOS/Linux hosts where podman was installed via an unusual prefix; scripts pinned to --engine podman running on developer machines that only have Docker Desktop.

Related errors

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