{"record":{"id":"d2d13bbcaad4a6d6","repo":"coleam00/Archon","slug":"resolvefolderbackend-called-for-non-folder-codebas","errorCode":null,"errorMessage":"resolveFolderBackend called for non-folder codebase '${codebase.name}' (kind: ${codebase.kind}). The backend seam is folder-only; repo projects use worktree isolation.","messagePattern":"resolveFolderBackend called for non-folder codebase '(.+?)' \\(kind: (.+?)\\)\\. The backend seam is folder-only; repo projects use worktree isolation\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/isolation/src/backend-router.ts","lineNumber":63,"sourceCode":" *   container (no silent container→host downgrade).\n */\n// Overloads: a `container: true` selection returns the CONCRETE ContainerBackend\n// (its Phase C write-back methods are required on that type), so the CLI can pass\n// it straight into the engine's write-back port without a runtime narrowing.\nexport function resolveFolderBackend(\n  codebase: BackendPrepareRequest['codebase'],\n  opts: ResolveFolderBackendOptions & { container: true }\n): ContainerBackend;\nexport function resolveFolderBackend(\n  codebase: BackendPrepareRequest['codebase'],\n  opts?: ResolveFolderBackendOptions\n): IIsolationBackend;\nexport function resolveFolderBackend(\n  codebase: BackendPrepareRequest['codebase'],\n  opts: ResolveFolderBackendOptions = {}\n): IIsolationBackend {\n  if (codebase.kind !== 'folder') {\n    throw new Error(\n      `resolveFolderBackend called for non-folder codebase '${codebase.name}' ` +\n        `(kind: ${codebase.kind}). The backend seam is folder-only; repo projects ` +\n        'use worktree isolation.'\n    );\n  }\n\n  if (opts.container) {\n    if (!opts.store || !opts.containerConfig) {\n      throw new Error(\n        'Container isolation was requested but is not wired up: the container ' +\n          'backend needs an isolation store and container config. This is a caller ' +\n          'bug — pass `store` and `containerConfig`, or run without `--container`.'\n      );\n    }\n    return new ContainerBackend({\n      store: opts.store,\n      config: opts.containerConfig,\n      ...(opts.dockerRunner ? { dockerRunner: opts.dockerRunner } : {}),","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/isolation/src/backend-router.ts#L45-L81","documentation":"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.","triggerScenarios":"Invoking resolveFolderBackend (directly or via the backend() router) with a BackendPrepareRequest whose codebase.kind is 'repo' or any value other than 'folder'.","commonSituations":"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.","solutions":["Route repo codebases through the worktree isolation path instead of resolveFolderBackend.","Check codebase.kind before selecting the backend and branch on 'folder' vs repo.","If the codebase should be folder-backed, re-register it with kind 'folder'.","Fix upstream callers (see the `backend` function) so the folder seam is only reached for folder codebases."],"exampleFix":"// before\nconst backend = resolveFolderBackend(codebase); // codebase.kind === 'repo'\n// after\nconst backend = codebase.kind === 'folder'\n  ? resolveFolderBackend(codebase)\n  : createWorktreeBackend(codebase);","handlingStrategy":"type-guard","validationCode":"function isFolderCodebase(cb: { kind: string }): boolean { return cb.kind === 'folder'; }\nif (!isFolderCodebase(codebase)) throw new Error('folder backend requires kind === folder');","typeGuard":"function isFolderCodebase(cb: BackendPrepareRequest['codebase']): cb is BackendPrepareRequest['codebase'] & { kind: 'folder' } {\n  return cb.kind === 'folder';\n}","tryCatchPattern":"try {\n  const backend = resolveFolderBackend(codebase);\n} catch (e) {\n  if (e.message.includes('resolveFolderBackend called for non-folder')) {\n    console.error('Route repo codebases through the worktree backend');\n  } else throw e;\n}","preventionTips":["Narrow codebase.kind with a type guard before selecting a backend.","Let the backend() router choose the seam; avoid calling resolveFolderBackend directly on raw codebases.","Re-check registrations after changing a codebase's kind."],"tags":["isolation","backend","type-mismatch","caller-bug"],"backgroundTag":"wrong-backend-for-codebase-kind","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}