jdx/mise · error

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

Error message

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

What it means

`--engine docker` explicitly demands docker. `select_engine` checks `file::which("docker")` and bails rather than falling back to podman, since the engine was explicitly requested. Auto mode would have picked podman if present.

Source

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

        } 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.")
            }
        }
    }
}

fn engine_name(engine: Engine) -> &'static str {
    match engine {
        Engine::Podman => "podman",

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

1. Install docker (Docker Desktop, or `apt install docker.io`)
2. Omit `--engine` to let Auto mode use podman if installed
3. Confirm visibility: `command -v docker`

Example fix

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

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

When it happens

Trigger: `mise oci run --engine docker ...` with no docker binary on PATH: Docker Desktop not installed/started on macOS/Windows, docker not installed in the CI image, or a rootless environment where only podman exists.

Common situations: Minimal CI containers (built from slim images) that never installed docker; docker installed but Docker Desktop daemon not running is a different failure — this one is purely binary-not-found; dev boxes that switched to podman.

Related errors

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

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