`docker load` failed ({status}): {stderr}. Ensure the docker

Error message

`docker load` failed ({status}): {stderr}. Ensure the docker daemon is running and your user has access to the socket.

What it means

After streaming the OCI image as a docker archive to `docker load`, mise checks the process exit status. This error is thrown when docker load exits non-zero, and appends docker's stderr plus a hint that the docker daemon may not be running or the user may lack socket access. A failure while writing the archive stream is also surfaced so the truncated-archive message from docker does not mask the real cause.

Source

Thrown at src/oci/docker_archive.rs:113

        .join()
        .map_err(|_| eyre::eyre!("docker archive writer thread panicked"))?;

    if !out.status.success() {
        let stderr = String::from_utf8_lossy(&out.stderr);
        let mut msg = format!(
            "`docker load` failed ({}): {}. Ensure the docker daemon is running and \
             your user has access to the socket.",
            out.status,
            stderr.trim()
        );
        // A write error here is usually the broken pipe caused by docker
        // dying (so docker's stderr is the real cause), but if it's something
        // else — e.g. a layer failed to decompress — surface it too so the
        // truncated-archive error from docker doesn't mask the root cause.
        if let Err(e) = &write_result {
            msg.push_str(&format!("\n(while writing archive: {e})"));
        }
        bail!(msg);
    }
    // docker succeeded — don't swallow a writer error if one somehow occurred.
    write_result?;
    Ok(())
}

fn write_docker_archive<W: Write>(
    out: W,
    layout: &ImageLayout,
    manifest: &ImageManifest,
    config_bytes: &[u8],
    tag: &str,
) -> Result<()> {
    let mut builder = Builder::new(out);

    let config_name = format!("{}.json", hex_of(&manifest.config.digest));
    append_bytes(&mut builder, &config_name, config_bytes)?;

View on GitHub (pinned to afd2eddd3a)

Solutions

Start the docker daemon (systemctl start docker / start Docker Desktop) and verify with `docker info`, then retry the load.
Fix socket permissions: `sudo usermod -aG docker $USER` (then re-login) or set DOCKER_HOST correctly to the daemon you intend to use.
Check the full message: if it includes "(while writing archive: ...)", fix the underlying archive write/decompression failure instead of docker itself.
Verify the source image layout is complete and valid (all blobs present) and rebuild it if it was truncated.

Example fix

// before
mise oci load ./out/image
// error: `docker load` failed ...
// after
sudo systemctl start docker
sudo usermod -aG docker $USER  # then re-login
mise oci load ./out/image

Defensive patterns

Strategy: try-catch

Validate before calling

if !command_exists("docker") { return Err("docker not installed"); }
let info = Command::new("docker").arg("info").output()?;
if !info.status.success() {
    return Err("docker daemon unreachable; start it or check DOCKER_HOST / socket permissions".into());
}

Try / catch

match load_into_docker(&dir) {
    Err(e) if e.to_string().contains("`docker load` failed") => {
        if e.to_string().contains("while writing archive") {
            eprintln!("archive write failed — rebuild the image layout");
        } else {
            eprintln!("start the docker daemon / fix socket access, then retry");
        }
    }
    r => r,
}

Prevention

Check `docker info` as a preflight before oci load.
Add your user to the docker group or run in an environment with the socket mounted.
Verify image archives are complete (checksums) before loading.

When it happens

Trigger: Running `mise oci load` (load_into_docker) when the docker daemon is stopped, the user is not in the docker group / lacks socket permissions, docker is not installed or DOCKER_HOST is wrong, or the image archive is corrupt so docker reports a truncated archive.

Common situations: CI without a running docker daemon; running inside a container without /var/run/docker.sock mounted; user not in the docker group after installing docker; disk-full or failed download producing a truncated layer tar.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/4ab7ee5e78befe71. Report an issue: GitHub.