coleam00/Archon · critical

Cannot connect to the Docker daemon. Is Docker running?${doc

Error message

Cannot connect to the Docker daemon. Is Docker running?${dockerizedHint} (${detail})

What it means

dockerPreflight verifies the Docker daemon is reachable before any container work. When a plain daemon ping fails, it throws this error, adding a special hint when Archon itself runs inside Docker (where the daemon socket is never mounted).

Source

Thrown at packages/isolation/src/container/docker-exec.ts:100

  runner: DockerRunner = dockerCli
): Promise<void> {
  // 1. Daemon reachable. `docker version --format {{.Server.Version}}` errors
  //    with "Cannot connect to the Docker daemon" when the daemon is down.
  try {
    await runner(['version', '--format', '{{.Server.Version}}'], { timeout: 10_000 });
  } catch (err) {
    const detail = extractDockerError(err);
    // When Archon itself runs in Docker (the compose stack), the app image ships
    // no `docker` CLI and the daemon socket is deliberately NOT mounted — so
    // `--container` cannot work here. Say so instead of the misleading generic
    // "is Docker running?" (see deployment/docker.md; the socket is root-equivalent).
    const dockerizedHint =
      process.env.ARCHON_DOCKER === 'true'
        ? ' Archon is running inside Docker, which does not mount the Docker daemon socket — ' +
          'the --container backend is unavailable in a dockerized deploy. Run Archon directly ' +
          'on the host, or see deployment/docker.md.'
        : '';
    throw new Error(
      `Cannot connect to the Docker daemon. Is Docker running?${dockerizedHint} (${detail})`
    );
  }

  // 2. Runner image present locally. We never auto-pull — the image is built
  //    from the in-repo Dockerfile, so a miss means "build it", not "pull it".
  try {
    await runner(['image', 'inspect', image], { timeout: 15_000 });
  } catch (err) {
    const detail = extractDockerError(err);
    throw new Error(
      `No such image: '${image}'. Build the runner image first: ` +
        `docker build -t ${image} -f packages/isolation/docker/runner.Dockerfile packages/isolation/docker (${detail})`
    );
  }
}

/**

View on GitHub (pinned to 0773b97458)

Solutions

  1. Start Docker (systemctl start docker / open Docker Desktop)
  2. If ARCHON_DOCKER=true, run Archon directly on the host or see deployment/docker.md
  3. Check DOCKER_HOST/DOCKER_CONTEXT point at a reachable daemon
  4. Fix socket permissions (add user to docker group, re-login)

Example fix

// before
export DOCKER_HOST=tcp://localhost:2375  # daemon not listening
// after
unset DOCKER_HOST  # use the local unix socket with a running daemon
Defensive patterns

Strategy: validation

Validate before calling

import { execFile } from 'child_process';
function dockerReachable(): Promise<boolean> {
  return new Promise(res => execFile('docker', ['info'], err => res(!err)));
}
if (!(await dockerReachable())) throw new Error('Start Docker before using --container');

Try / catch

try {
  await backend.prepare(opts);
} catch (err) {
  if (String(err).includes('Cannot connect to the Docker daemon')) {
    if (process.env.ARCHON_DOCKER === 'true') {
      // dockerized deploy: run Archon on the host instead
    }
  }
  throw err;
}

Prevention

When it happens

Trigger: Calling prepare()/p() with the --container backend when the Docker daemon is not running, the socket is not accessible, or DOCKER_HOST points at an unreachable daemon.

Common situations: Docker Desktop not started; user not in the docker group; running inside a dockerized Archon deploy (ARCHON_DOCKER=true) without the socket; DOCKER_HOST misconfigured after switching contexts.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/4e4a446e1f1e73bf. Report an issue: GitHub.