{"record":{"id":"7d6413643ddaf597","repo":"coleam00/Archon","slug":"cannot-register-folder-project-error-error-mes","errorCode":null,"errorMessage":"Cannot register folder project.\nError: ${error.message}\nHint: Check that the directory is readable and your Archon home (~/.archon) is writable, then retry.","messagePattern":"Cannot register folder project\\.\nError: (.+?)\nHint: Check that the directory is readable and your Archon home \\(~/\\.archon\\) is writable, then retry\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/workflow.ts","lineNumber":2022,"sourceCode":"    // log. A launch either produces a run id somebody can query, or it fails right\n    // here with a non-zero exit. The fork itself has not moved — no worktree, clone,\n    // or AI cost happens in this process.\n    //\n    // The project lookup was a best-effort folder probe; it is now the same resolution\n    // the run path performs, because the run row needs `codebase_id` and adoption\n    // cannot be judged without it. Registration is idempotent, so the child's own call\n    // finds what this one registered.\n    const detachResolved = await resolveRunCodebase(cwd, options);\n    const detachCodebase = detachResolved.codebase;\n    // Never on `--json`: stdout carries one machine-readable document and nothing else.\n    if (detachResolved.registeredFolder && !options.json) {\n      console.log(\n        `Registered folder project \"${detachResolved.registeredFolder.name}\" ` +\n          `(${detachResolved.registeredFolder.defaultCwd})`\n      );\n    }\n    if (options.folder && !detachCodebase && detachResolved.registrationError) {\n      throw buildFolderRegistrationFailureError(detachResolved.registrationError);\n    }\n    // The refusal the plain `run <name> --detach` launch was still missing: an isolating\n    // run with no project to isolate. The isolation block enforces it in whichever\n    // process reaches it, which for a detached launch is the child — after the parent has\n    // already printed `Started` (#2872). `options.noWorktree` first, mirroring the\n    // isolation block's own branch order.\n    if (!options.noWorktree && wantsIsolation) {\n      assertCodebaseResolvedForIsolation(detachResolved);\n    }\n    // Never pin a worktree branch on the child for a folder project. The --folder flag\n    // declares it; an already-registered folder project is read off the resolution.\n    const detachIsFolder = options.folder === true || detachCodebase?.kind === 'folder';\n    // Surface worktree-option conflicts synchronously in the parent rather than\n    // letting the child fail after fork.\n    assertNoWorktreeOptionsForFolder(detachIsFolder, options);\n\n    // Between-run continuation (#2747): refuse an unresolvable declaration HERE — this\n    // is the exact failure that vanished into a child log. `resolveWorkflowAdoption` is","sourceCodeStart":2004,"sourceCodeEnd":2040,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/cli/src/commands/workflow.ts#L2004-L2040","documentation":"`archon workflow run <name> --detach --folder` performs a pre-flight project resolution (resolveRunCodebase) in the parent before forking, so a detached launch never prints 'Started' and then dies in the child (#2872). When --folder was requested, no codebase could be resolved, and the resolution recorded a registrationError, the CLI throws buildFolderRegistrationFailureError: 'Cannot register folder project.\\nError: ...\\nHint: Check that the directory is readable and your Archon home (~/.archon) is writable, then retry.'","triggerScenarios":"Running `archon workflow run <name> --detach --folder` (or the attach path with options.folder at workflow.ts:2022) where resolveRunCodebase fails to register the folder as a project — unreadable target directory, unwritable ~/.archon home, or an underlying registration store error.","commonSituations":"Pointing --folder at a nonexistent or permission-denied directory; running under a user whose ~/.archon is not writable (wrong user, read-only home, sandboxed container); disk-full or corrupted local registration state.","solutions":["Verify the --folder directory exists and is readable by the current user","Check that ~/.archon exists and is writable (fix ownership/permissions)","Retry the command after fixing; registration is idempotent","If the database is also required, confirm DATABASE_URL connectivity, since registration may touch it"],"exampleFix":"// before\nawait exec(`archon workflow run fix-issue --detach --folder ${badPath}`);\n// after\nimport { accessSync, constants } from 'node:fs';\naccessSync(badPath, constants.R_OK); // fail fast with a clear error\nawait exec(`archon workflow run fix-issue --detach --folder ${goodPath}`);","handlingStrategy":"validation","validationCode":"import { accessSync, constants } from 'node:fs';\nimport { join } from 'node:path';\nfunction assertFolderRegistrable(folder) {\n  accessSync(folder, constants.R_OK);            // readable target\n  accessSync(join(process.env.HOME ?? '', '.archon'), constants.W_OK); // writable home\n}\nassertFolderRegistrable(folderPath); // before `run --detach --folder`","typeGuard":null,"tryCatchPattern":"try {\n  await runWorkflow(name, { detach: true, folder: true });\n} catch (e) {\n  if (String(e.message).startsWith('Cannot register folder project.')) {\n    // check dir readability and ~/.archon writability, then retry\n  } else throw e;\n}","preventionTips":["Stat the --folder path and ~/.archon permissions before launching detached runs","Run the CLI as a user that owns or can write ~/.archon","Use the non-detach form first to surface registration errors synchronously","In containers, mount a writable home for the CLI user"],"tags":["cli","filesystem","project-registration","detach"],"backgroundTag":"folder-registration-failed","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}