Cannot register folder project. Error: ${error.message} Hint

Error message

Cannot register folder project.
Error: ${error.message}
Hint: Check that the directory is readable and your Archon home (~/.archon) is writable, then retry.

What it means

`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.'

Source

Thrown at packages/cli/src/commands/workflow.ts:2022

    // log. A launch either produces a run id somebody can query, or it fails right
    // here with a non-zero exit. The fork itself has not moved — no worktree, clone,
    // or AI cost happens in this process.
    //
    // The project lookup was a best-effort folder probe; it is now the same resolution
    // the run path performs, because the run row needs `codebase_id` and adoption
    // cannot be judged without it. Registration is idempotent, so the child's own call
    // finds what this one registered.
    const detachResolved = await resolveRunCodebase(cwd, options);
    const detachCodebase = detachResolved.codebase;
    // Never on `--json`: stdout carries one machine-readable document and nothing else.
    if (detachResolved.registeredFolder && !options.json) {
      console.log(
        `Registered folder project "${detachResolved.registeredFolder.name}" ` +
          `(${detachResolved.registeredFolder.defaultCwd})`
      );
    }
    if (options.folder && !detachCodebase && detachResolved.registrationError) {
      throw buildFolderRegistrationFailureError(detachResolved.registrationError);
    }
    // The refusal the plain `run <name> --detach` launch was still missing: an isolating
    // run with no project to isolate. The isolation block enforces it in whichever
    // process reaches it, which for a detached launch is the child — after the parent has
    // already printed `Started` (#2872). `options.noWorktree` first, mirroring the
    // isolation block's own branch order.
    if (!options.noWorktree && wantsIsolation) {
      assertCodebaseResolvedForIsolation(detachResolved);
    }
    // Never pin a worktree branch on the child for a folder project. The --folder flag
    // declares it; an already-registered folder project is read off the resolution.
    const detachIsFolder = options.folder === true || detachCodebase?.kind === 'folder';
    // Surface worktree-option conflicts synchronously in the parent rather than
    // letting the child fail after fork.
    assertNoWorktreeOptionsForFolder(detachIsFolder, options);

    // Between-run continuation (#2747): refuse an unresolvable declaration HERE — this
    // is the exact failure that vanished into a child log. `resolveWorkflowAdoption` is

View on GitHub (pinned to 0773b97458)

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

Example fix

// before
await exec(`archon workflow run fix-issue --detach --folder ${badPath}`);
// after
import { accessSync, constants } from 'node:fs';
accessSync(badPath, constants.R_OK); // fail fast with a clear error
await exec(`archon workflow run fix-issue --detach --folder ${goodPath}`);

Defensive patterns

Strategy: validation

Validate before calling

import { accessSync, constants } from 'node:fs';
import { join } from 'node:path';
function assertFolderRegistrable(folder) {
  accessSync(folder, constants.R_OK);            // readable target
  accessSync(join(process.env.HOME ?? '', '.archon'), constants.W_OK); // writable home
}
assertFolderRegistrable(folderPath); // before `run --detach --folder`

Try / catch

try {
  await runWorkflow(name, { detach: true, folder: true });
} catch (e) {
  if (String(e.message).startsWith('Cannot register folder project.')) {
    // check dir readability and ~/.archon writability, then retry
  } else throw e;
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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