coleam00/Archon · error

resolveFolderBackend called for non-folder codebase '${codeb

Error message

resolveFolderBackend called for non-folder codebase '${codebase.name}' (kind: ${codebase.kind}). The backend seam is folder-only; repo projects use worktree isolation.

What it means

resolveFolderBackend is the folder-only seam of the isolation backend router: it selects a backend for codebases of kind 'folder'. Calling it with a repo-kind codebase is a programming/caller bug because repo projects get worktree isolation through a different path, so it throws a descriptive error naming both the codebase and its kind.

Source

Thrown at packages/isolation/src/backend-router.ts:63

 *   container (no silent container→host downgrade).
 */
// Overloads: a `container: true` selection returns the CONCRETE ContainerBackend
// (its Phase C write-back methods are required on that type), so the CLI can pass
// it straight into the engine's write-back port without a runtime narrowing.
export function resolveFolderBackend(
  codebase: BackendPrepareRequest['codebase'],
  opts: ResolveFolderBackendOptions & { container: true }
): ContainerBackend;
export function resolveFolderBackend(
  codebase: BackendPrepareRequest['codebase'],
  opts?: ResolveFolderBackendOptions
): IIsolationBackend;
export function resolveFolderBackend(
  codebase: BackendPrepareRequest['codebase'],
  opts: ResolveFolderBackendOptions = {}
): IIsolationBackend {
  if (codebase.kind !== 'folder') {
    throw new Error(
      `resolveFolderBackend called for non-folder codebase '${codebase.name}' ` +
        `(kind: ${codebase.kind}). The backend seam is folder-only; repo projects ` +
        'use worktree isolation.'
    );
  }

  if (opts.container) {
    if (!opts.store || !opts.containerConfig) {
      throw new Error(
        'Container isolation was requested but is not wired up: the container ' +
          'backend needs an isolation store and container config. This is a caller ' +
          'bug — pass `store` and `containerConfig`, or run without `--container`.'
      );
    }
    return new ContainerBackend({
      store: opts.store,
      config: opts.containerConfig,
      ...(opts.dockerRunner ? { dockerRunner: opts.dockerRunner } : {}),

View on GitHub (pinned to 0773b97458)

Solutions

1. Route repo codebases through the worktree isolation path instead of resolveFolderBackend.
2. Check codebase.kind before selecting the backend and branch on 'folder' vs repo.
3. If the codebase should be folder-backed, re-register it with kind 'folder'.
4. Fix upstream callers (see the `backend` function) so the folder seam is only reached for folder codebases.

Example fix

// before
const backend = resolveFolderBackend(codebase); // codebase.kind === 'repo'
// after
const backend = codebase.kind === 'folder'
  ? resolveFolderBackend(codebase)
  : createWorktreeBackend(codebase);

function isFolderCodebase(cb: { kind: string }): boolean { return cb.kind === 'folder'; }
if (!isFolderCodebase(codebase)) throw new Error('folder backend requires kind === folder');

function isFolderCodebase(cb: BackendPrepareRequest['codebase']): cb is BackendPrepareRequest['codebase'] & { kind: 'folder' } {
  return cb.kind === 'folder';
}

try {
  const backend = resolveFolderBackend(codebase);
} catch (e) {
  if (e.message.includes('resolveFolderBackend called for non-folder')) {
    console.error('Route repo codebases through the worktree backend');
  } else throw e;
}

When it happens

Trigger: Invoking resolveFolderBackend (directly or via the backend() router) with a BackendPrepareRequest whose codebase.kind is 'repo' or any value other than 'folder'.

Common situations: Wiring a custom dispatch path that always calls resolveFolderBackend regardless of codebase kind; a migration that changed codebase.kind from folder to repo without updating the backend selection; copy-pasted router code applied to repo projects.

Related errors

• Container isolation was requested but is not wired up: the c
• Container isolation is folder-project-only for now. Run --co
• classifyIsolationError(err)
• Isolation resolution stuck in stale_cleaned loop for convers
• Isolation environment required but could not be created

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