{"record":{"id":"f4456cd52bd96edc","repo":"coleam00/Archon","slug":"container-overlay-did-not-become-ready-logs","errorCode":null,"errorMessage":"Container overlay did not become ready.${logs ? ` Container logs:\\n${logs}` : ''}","messagePattern":"Container overlay did not become ready\\.(.+?)` : ''\\}","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/isolation/src/backends/container.ts","lineNumber":693,"sourceCode":"        return;\n      } catch {\n        // Not ready yet. ONLY fast-fail when the container has DEFINITELY exited\n        // (`Running=false`) — a transient inspect error/timeout must NOT be read\n        // as \"stopped\", or an infra blip would silently trigger the native +\n        // CAP_SYS_ADMIN fallback (privilege broadening). On 'unknown' keep polling\n        // until the deadline (a real exit still surfaces via the timeout).\n        if ((await this.containerState(containerId)) === 'stopped') break;\n        await new Promise(resolve => setTimeout(resolve, READY_POLL_INTERVAL_MS));\n      }\n    }\n    let logs = '';\n    try {\n      const { stdout, stderr } = await this.docker(['logs', '--tail', '20', containerId]);\n      logs = `${stdout}\\n${stderr}`.trim();\n    } catch {\n      // Best-effort — the timeout / exit is the real error.\n    }\n    throw new Error(\n      `Container overlay did not become ready.${logs ? ` Container logs:\\n${logs}` : ''}`\n    );\n  }\n\n  /**\n   * Container running state as three distinct outcomes. Crucially, an inspect\n   * ERROR (daemon timeout, transient failure) is `unknown`, NOT `stopped` — the\n   * caller must not treat \"couldn't tell\" as \"exited\" (see waitForReady: only an\n   * explicit `stopped` may fast-fail into the privileged native fallback).\n   */\n  private async containerState(containerId: string): Promise<'running' | 'stopped' | 'unknown'> {\n    try {\n      const { stdout } = await this.docker(['inspect', '-f', '{{.State.Running}}', containerId], {\n        timeout: 5_000,\n      });\n      const value = stdout.trim();\n      if (value === 'true') return 'running';\n      if (value === 'false') return 'stopped';","sourceCodeStart":675,"sourceCodeEnd":711,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/isolation/src/backends/container.ts#L675-L711","documentation":"waitForReady polls the container until its overlay setup signals readiness. On timeout/exit it captures the last 20 lines of container logs and throws this error with those logs attached for diagnosis.","triggerScenarios":"A container started via startContainerWithOverlay or resumed via resumeEnv never emits its ready signal within the timeout — the overlay mount script hangs or the container crashes during init.","commonSituations":"fuse-overlayfs stalling on a misconfigured /dev/fuse; runner image missing the ready-signal script; slow host I/O exceeding the readiness timeout; container OOM-killed during mount.","solutions":["Read the attached container logs in the error message to find the mount failure","Verify the runner image contains the overlay init script and it runs to completion","Increase the readiness timeout on slow hosts","Ensure /dev/fuse and required capabilities are present when using fuse-overlayfs"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// verify image contains the overlay init script before starting\ndocker run --rm <image> test -x /path/to/overlay-init || echo 'image missing init script'","typeGuard":null,"tryCatchPattern":"try {\n  await backend.resumeEnv(envId);\n} catch (err) {\n  if (String(err).startsWith('Container overlay did not become ready')) {\n    // err.message contains the last 20 container log lines — inspect them\n    const logs = err.message.split('Container logs:\\n')[1];\n    console.error('readiness logs:', logs);\n  }\n  throw err;\n}","preventionTips":["Ensure the runner image's overlay init script emits the ready signal","Allow generous timeouts on slow/I/O-bound hosts","Monitor container memory to avoid OOM during mount"],"tags":["docker","overlayfs","timeout"],"backgroundTag":"container-readiness-timeout","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}