{"record":{"id":"4e4a446e1f1e73bf","repo":"coleam00/Archon","slug":"cannot-connect-to-the-docker-daemon-is-docker-run","errorCode":null,"errorMessage":"Cannot connect to the Docker daemon. Is Docker running?${dockerizedHint} (${detail})","messagePattern":"Cannot connect to the Docker daemon\\. Is Docker running\\?(.+?) \\((.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/isolation/src/container/docker-exec.ts","lineNumber":100,"sourceCode":"  runner: DockerRunner = dockerCli\n): Promise<void> {\n  // 1. Daemon reachable. `docker version --format {{.Server.Version}}` errors\n  //    with \"Cannot connect to the Docker daemon\" when the daemon is down.\n  try {\n    await runner(['version', '--format', '{{.Server.Version}}'], { timeout: 10_000 });\n  } catch (err) {\n    const detail = extractDockerError(err);\n    // When Archon itself runs in Docker (the compose stack), the app image ships\n    // no `docker` CLI and the daemon socket is deliberately NOT mounted — so\n    // `--container` cannot work here. Say so instead of the misleading generic\n    // \"is Docker running?\" (see deployment/docker.md; the socket is root-equivalent).\n    const dockerizedHint =\n      process.env.ARCHON_DOCKER === 'true'\n        ? ' Archon is running inside Docker, which does not mount the Docker daemon socket — ' +\n          'the --container backend is unavailable in a dockerized deploy. Run Archon directly ' +\n          'on the host, or see deployment/docker.md.'\n        : '';\n    throw new Error(\n      `Cannot connect to the Docker daemon. Is Docker running?${dockerizedHint} (${detail})`\n    );\n  }\n\n  // 2. Runner image present locally. We never auto-pull — the image is built\n  //    from the in-repo Dockerfile, so a miss means \"build it\", not \"pull it\".\n  try {\n    await runner(['image', 'inspect', image], { timeout: 15_000 });\n  } catch (err) {\n    const detail = extractDockerError(err);\n    throw new Error(\n      `No such image: '${image}'. Build the runner image first: ` +\n        `docker build -t ${image} -f packages/isolation/docker/runner.Dockerfile packages/isolation/docker (${detail})`\n    );\n  }\n}\n\n/**","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/isolation/src/container/docker-exec.ts#L82-L118","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Start Docker (systemctl start docker / open Docker Desktop)","If ARCHON_DOCKER=true, run Archon directly on the host or see deployment/docker.md","Check DOCKER_HOST/DOCKER_CONTEXT point at a reachable daemon","Fix socket permissions (add user to docker group, re-login)"],"exampleFix":"// before\nexport DOCKER_HOST=tcp://localhost:2375  # daemon not listening\n// after\nunset DOCKER_HOST  # use the local unix socket with a running daemon","handlingStrategy":"validation","validationCode":"import { execFile } from 'child_process';\nfunction dockerReachable(): Promise<boolean> {\n  return new Promise(res => execFile('docker', ['info'], err => res(!err)));\n}\nif (!(await dockerReachable())) throw new Error('Start Docker before using --container');","typeGuard":null,"tryCatchPattern":"try {\n  await backend.prepare(opts);\n} catch (err) {\n  if (String(err).includes('Cannot connect to the Docker daemon')) {\n    if (process.env.ARCHON_DOCKER === 'true') {\n      // dockerized deploy: run Archon on the host instead\n    }\n  }\n  throw err;\n}","preventionTips":["Start Docker Desktop/daemon before launching Archon","Do not run the container backend inside a dockerized Archon deploy","Keep DOCKER_HOST unset or pointing at a live daemon"],"tags":["docker","daemon","connectivity"],"backgroundTag":"docker-daemon-unreachable","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}