coleam00/Archon · error

Could not mount the overlay in any mode. Native overlay need

Error message

Could not mount the overlay in any mode. Native overlay needs CAP_SYS_ADMIN; fuse-overlayfs needs /dev/fuse AND an unprivileged-mount daemon (rootless / userns-remap). Attempts:\n${failures.join('\n')}

What it means

startContainerWithOverlay tries mounting the overlay filesystem inside the runner container in several modes (native overlayfs, then fuse-overlayfs). If every mode fails, it throws this aggregate error listing each attempt's failure detail.

Source

Thrown at packages/isolation/src/backends/container.ts:594

      try {
        await this.waitForReady(containerId);
        if (mode !== OVERLAY_MODES[0]) {
          log.warn({ containerName, mode }, 'isolation.container_overlay_fallback');
        }
        return { containerId, mode };
      } catch (readyErr) {
        // Container started but the mount failed (entrypoint exits fast) — remove
        // it so the name is free for the next mode, then continue.
        failures.push(`${mode}: ${(readyErr as Error).message}`);
        await this.docker(['rm', '-f', containerName]).catch(rmErr => {
          log.warn(
            { containerName, mode, detail: extractDockerError(rmErr) },
            'isolation.container_fallback_cleanup_failed'
          );
        });
      }
    }
    throw new Error(
      'Could not mount the overlay in any mode. Native overlay needs CAP_SYS_ADMIN; ' +
        'fuse-overlayfs needs /dev/fuse AND an unprivileged-mount daemon ' +
        `(rootless / userns-remap). Attempts:\n${failures.join('\n')}`
    );
  }

  /**
   * `docker run -d` the runner image in the given overlay mode. `fuse` grants
   * only `--device /dev/fuse` (no CAP_SYS_ADMIN); `native` grants
   * `--cap-add SYS_ADMIN --security-opt apparmor=unconfined` (no device). The
   * entrypoint mounts per `ARCHON_OVERLAY_MODE`.
   *
   * @returns the full container id from `docker run`'s stdout.
   */
  private async runContainerInMode(
    containerName: string,
    volume: string,
    hostRoot: string,

View on GitHub (pinned to 0773b97458)

Solutions

1. Run Docker as root (non-rootless) or enable CAP_SYS_ADMIN on the runner container
2. Expose /dev/fuse to the container and install fuse-overlayfs in the runner image
3. If rootless, ensure the rootless daemon supports unprivileged overlay mounts (kernel >= 5.11 with fuse-overlayfs configured)
4. Fall back to a non-overlay isolation backend if the host cannot support either mode

// best-effort: check capabilities before attempting overlay
const caps = process.env.DOCKER_HOST?.includes('rootless') || process.env.USERNS_REMAP
  ? 'rootless'
  : 'rootful';
if (caps === 'rootless') console.warn('overlay may need fuse-overlayfs + /dev/fuse');

try {
  await backend.prepare(opts);
} catch (err) {
  if (String(err).startsWith('Could not mount the overlay in any mode')) {
    // inspect err message 'Attempts:' section; switch backend or fix host capabilities
  }
  throw err;
}

When it happens

Trigger: prepare()/resume start a container where native overlay lacks CAP_SYS_ADMIN and fuse-overlayfs lacks /dev/fuse or the unprivileged-mount daemon (rootless/userns-remap Docker).

Common situations: Rootless Docker without /dev/fuse exposed; userns-remap daemon blocking privileged mounts; hardened hosts (gVisor/Kata) not implementing overlayfs; restricted container runtime capabilities.

Related errors

• Container overlay did not become ready.${logs ? ` Container
• Failed to inspect the overlay diff: ${extractDockerError(err
• Write-back apply failed partway (${landed} path(s) already a
• Repository ${owner}/${repo} not found or is private. Check r
• Authentication failed for ${owner}/${repo}. ${authHint}

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