Failed to inspect the overlay diff: ${extractDockerError(err

Error message

Failed to inspect the overlay diff: ${extractDockerError(err)}

What it means

summarizeOverlayChanges inspects the overlay diff by running docker commands that diff the overlay's upper layer against the lower layer. If the docker invocation fails, the raw docker error is extracted and rethrown wrapped in this message.

Source

Thrown at packages/isolation/src/container/overlay.ts:125

      ...HELPER_HARDENING,
      // Bypass the runner image ENTRYPOINT (the overlay-mount entrypoint that needs
      // ARCHON_WORKSPACE_PATH) — this helper only reads the volume, no overlay mount.
      '--entrypoint',
      'bash',
      '-v',
      `${target.volume}:/upper:ro`,
      '-v',
      `${target.hostRoot}:/lower:ro`,
      target.image,
      '-c',
      buildSummaryScript(),
      'archon-overlay',
      `/upper/${UPPER_DATA_SUBPATH}`,
      '/lower',
      target.hostRoot,
    ]));
  } catch (err) {
    throw new Error(`Failed to inspect the overlay diff: ${extractDockerError(err)}`);
  }

  const added: string[] = [];
  const modified: string[] = [];
  const deleted: string[] = [];
  const symlinks: { path: string; target: string; escapes: boolean }[] = [];
  const skipped: { path: string; reason: string }[] = [];
  let total = 0;

  for (const { tag, fields } of parseRecords(stdout)) {
    const path = fields[0] ?? '';
    if (tag === 'A') {
      total++;
      pushCapped(added, path);
    } else if (tag === 'M') {
      total++;
      pushCapped(modified, path);
    } else if (tag === 'D') {

View on GitHub (pinned to 0773b97458)

Solutions

Run the docker diff command manually to see the raw failure
Ensure the container still exists and is running before summarizing
Check Docker daemon health and socket permissions
Re-run the summary after daemon/container access is restored

Defensive patterns

Strategy: try-catch

Validate before calling

const state = await backend.presence(containerName);
if (state !== 'running') throw new Error('container must be running before summarize');

Try / catch

try {
  const summary = await backend.summary(envId);
} catch (err) {
  if (String(err).startsWith('Failed to inspect the overlay diff')) {
    // container/daemon state changed; verify container is running and retry
  }
  throw err;
}

Prevention

Only summarize while the container is running and before cleanup
Verify daemon health before summary operations
Avoid stopping/removing the container concurrently

When it happens

Trigger: Calling summary/changeSummary when the docker diff/inspect command fails — daemon unreachable, container removed mid-call, or the overlay directories missing on the host.

Common situations: Container stopped/removed between start and summary; daemon restarted; host root path (hostRoot) no longer accessible; Docker daemon permission problems.

Related errors

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