{"record":{"id":"3f89f5faecc64e18","repo":"Hmbown/CodeWhale","slug":"spawn-failed","errorCode":"spawn_failed","errorMessage":"docker ${args[0]} timed out","messagePattern":"docker (.+?) timed out","errorType":"error_code","errorClass":"SpawnError","httpStatus":null,"severity":"error","filePath":"crates/tui/plugins/computer-use/src/spawn.mjs","lineNumber":43,"sourceCode":"\nclass SpawnError extends ExecError {\n  constructor(code, message, result) {\n    super(message, result);\n    this.code = code;\n  }\n}\n\nfunction docker(args, opts = {}) {\n  // Docker CLI lives off PATH; on macOS a Colima/Docker-Desktop install puts\n  // it in /usr/local/bin or /opt/homebrew/bin which the MCP host's PATH may\n  // lack, so try the well-known paths too.\n  return run(\"docker\", args, opts);\n}\n\nasync function dockerOk(args, opts = {}) {\n  const r = await docker(args, opts);\n  if (r.aborted) throw Object.assign(new ExecError(\"computer request cancelled\", r), { code: \"cancelled\" });\n  if (r.timedOut) throw new SpawnError(\"spawn_failed\", `docker ${args[0]} timed out`, r);\n  if (r.code !== 0) throw new SpawnError(\"spawn_failed\", `docker ${args[0]} failed: ${trim(r.stderr || r.stdout)}`, r);\n  return r;\n}\n\nexport async function dockerAvailable(command = docker) {\n  const r = await command([\"info\", \"--format\", \"{{.OSType}}\"], { timeoutMs: 10_000 });\n  return r.code === 0 && !r.timedOut && !r.aborted && r.stdout.trim() === \"linux\";\n}\n\n/**\n * The image must exist locally. The plugin's own image is built from\n * docker/Dockerfile on first use; any other image name is the caller's\n * responsibility — we never guess a build context for it.\n */\nasync function ensureImage(image) {\n  const inspect = await docker([\"image\", \"inspect\", image], { timeoutMs: 15_000 });\n  if (inspect.code === 0) return { built: false };\n  if (image !== DEFAULT_IMAGE) {","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/plugins/computer-use/src/spawn.mjs#L25-L61","documentation":"Thrown by dockerOk() when a docker CLI invocation exceeds its per-command timeout. dockerOk wraps all docker calls used to validate/read the Docker engine state, and any command that neither aborted nor exited but hit its time budget produces this error instead of hanging forever. The message names the docker subcommand that timed out.","triggerScenarios":"Any dockerOk() call (e.g. dockerAvailable's 'docker info' with timeoutMs: 10_000, or 'image inspect' with 15s) where the spawned docker process runs past its timeoutMs and sets r.timedOut.","commonSituations":"Docker Desktop is starting up or wedged, the docker daemon is unresponsive under heavy load, disk I/O saturation slows the CLI, or a network-attached engine (Colima, remote DOCKER_HOST) is unreachable and the CLI stalls instead of failing fast.","solutions":["Check `docker info` in a terminal; if it hangs, restart the Docker daemon / Docker Desktop.","Retry the operation once the engine responds — this is usually transient daemon latency.","If on Colima or a remote DOCKER_HOST, verify the engine is running and reachable (`colima status`, `docker context ls`).","If the command legitimately needs longer, pass a larger timeoutMs in opts to the plugin's docker calls."],"exampleFix":"// before\ndockerOk([\"image\", \"inspect\", image]); // default timeout, stalls on slow daemon\n// after\nawait dockerOk([\"image\", \"inspect\", image], { timeoutMs: 30_000 });","handlingStrategy":"retry","validationCode":"// preflight probe\nconst ok = await dockerAvailable(); // runs docker info with a 10s budget\nif (!ok) throw new Error(\"docker engine not responding\");","typeGuard":null,"tryCatchPattern":"try {\n  await spawnDockerComputer();\n} catch (e) {\n  if (e?.code === \"spawn_failed\" && /timed out/.test(e.message)) {\n    // wait, confirm `docker info` responds, then retry once\n  }\n}","preventionTips":["Ensure the Docker daemon is running and warm before spawning.","Keep a preflight `docker info` health check in your startup path.","Pass generous timeoutMs for commands on slow or remote engines.","Avoid spawning while the host is under heavy I/O load."],"tags":["docker","timeout","spawn","network"],"backgroundTag":"request-timeout","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}