Write-back apply failed partway

Error message

Write-back apply failed partway (${landed} path(s) already applied to the live root — inspect and reconcile manually): ${detail}

What it means

applyOverlayChanges writes overlay-layer changes back to the live host root in one batched apply. If the apply command fails mid-way, the library parses partial machine-readable output to count how many paths (W/K/D records) already landed, then throws this error telling the operator the write-back is partially applied.

Solutions

Inspect the live root and reconcile the paths listed as already applied (count in the message)
Free disk space or fix host-root permissions, then re-run the apply
Take a backup of the live root before re-applying
Re-run applyOverlayChanges to apply the remaining paths

Defensive patterns

Strategy: try-catch

Validate before calling

// check space and permissions on the live root before apply
df -h <hostRoot>
test -w <hostRoot> && echo writable || echo 'host root not writable'

Try / catch

try {
  await backend.summary(envId, { apply: true });
} catch (err) {
  const m = String(err);
  if (m.startsWith('Write-back apply failed partway')) {
    const landed = /\((\d+) path/.exec(m)?.[1];
    // reconcile the ${landed} already-applied paths manually before retrying
  }
  throw err;
}

Prevention

Back up the live root before applying overlay changes
Ensure ample disk space and correct ownership on the host root
Do not kill the container or daemon mid-apply
Apply changes exclusively (avoid concurrent edits of the live root)

When it happens

Trigger: The batched write-back command (tar/cp/rsync via docker) fails after some records were applied — e.g. disk full, permission denied on the host root, or the docker exec dies mid-stream.

Common situations: Host root owned by another user (permission denied partway through); ENOSPC on the host; container killed during apply; concurrent modification of the live root.

Related errors

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

Appendix: source

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

      '-v',
      `${target.volume}:/upper:ro`,
      '-v',
      `${target.hostRoot}:/dest`,
      target.image,
      '-c',
      buildApplyScript(),
      'archon-overlay',
      `/upper/${UPPER_DATA_SUBPATH}`,
      '/dest',
      target.hostRoot,
    ]));
  } catch (err) {
    const detail = extractDockerError(err);
    const partial = (err as { stdout?: string }).stdout ?? '';
    const landed = parseRecords(partial).filter(
      r => r.tag === 'W' || r.tag === 'K' || r.tag === 'D'
    ).length;
    throw new Error(
      `Write-back apply failed partway (${landed} path(s) already applied to the live ` +
        `root — inspect and reconcile manually): ${detail}`
    );
  }

  let filesApplied = 0;
  let filesDeleted = 0;
  const warnings: string[] = [];
  for (const { tag, fields } of parseRecords(stdout)) {
    if (tag === 'W' || tag === 'K') filesApplied++;
    else if (tag === 'D') filesDeleted++;
    else if (tag === 'S') warnings.push(`skipped ${fields[0] ?? ''}: ${fields[1] ?? 'refused'}`);
  }
  // The helper also prints refusals/skips to stderr for the operator log.
  if (stderr.trim()) warnings.push(...stderr.trim().split('\n'));
  log.info({ filesApplied, filesDeleted, volume: target.volume }, 'isolation.overlay_applied');
  return { filesApplied, filesDeleted, warnings };
}

View on GitHub (pinned to 0773b97458)