coleam00/Archon · error · Error

Cannot create worktree: repository registration…

Error message

Cannot create worktree: repository registration failed.
Error: ${error.message}
${hint}

What it means

assertCodebaseResolvedForIsolation() distinguishes a failed lookup (previous error) from a failed registration. When the codebase was absent and codebaseDb's register attempt failed, buildRegistrationFailureError produces this refusal: the repo could not be registered, so a worktree cannot be safely created. The original error and a hint are appended (hint varies per call site context).

Solutions

Read the embedded registration error and fix the underlying DB write problem (permissions, disk space, connectivity).
Retry the run — a concurrent-registration race often resolves on a second attempt.
Use --no-worktree to skip worktree isolation if registration is not required for this run.
Verify database migrations/adapter health if constraint errors persist.

Example fix

// before: SQLite db is read-only
Error: Cannot create worktree: repository registration failed.
Error: attempt to write a readonly database
// after
$ chmod u+w ~/.archon/archon.db && archon workflow run foo

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure the codebase is already registered to avoid a registration write at run time
import { codebaseDb } from '@archon/core';
const resolved = await codebaseDb.getCodebase(cwd);
if (!resolved.codebase) console.warn('Repo not registered yet; registration write will occur during the run.');

Try / catch

try {
  await runWorkflow(name, opts);
} catch (e) {
  const msg = String((e as Error).message);
  if (msg.includes('repository registration failed')) {
    console.error('Fix the DB write problem (permissions/space/connectivity) per the embedded error:', msg);
  }
}

Prevention

Keep the Archon database writable by the user running the CLI.
Watch disk space on the volume holding the DB.
Register repos ahead of time instead of relying on first-run registration.
Retry once on transient DB errors before escalating.

When it happens

Trigger: First run in a git repository that is not yet in the codebase table; the registration INSERT/UPSERT to the workflow/codebase DB throws (DB unwritable, constraint failure, connection drop); assertCodebaseResolvedForIsolation then throws via buildRegistrationFailureError('create worktree', error).

Common situations: Read-only database file while Archon needs to write a new repo row; schema/adapter mismatch; unique-constraint race when two runs register the same repo concurrently; remote DB temporarily unavailable during first-time setup.

Related errors

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

Appendix: source

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

 * the pre-flight calls it unconditionally for an isolating run.
 */
function assertCodebaseResolvedForIsolation(resolved: {
  codebase: Awaited<ReturnType<typeof codebaseDb.getCodebase>>;
  lookupError: Error | null;
  registrationError: Error | null;
}): void {
  if (resolved.codebase) return;
  if (resolved.lookupError) {
    throw new Error(
      'Cannot create worktree: database lookup failed.\n' +
        `Error: ${resolved.lookupError.message}\n` +
        'Hint: Check your database connection, or use --no-worktree to skip isolation.'
    );
  }
  if (resolved.registrationError) {
    throw buildRegistrationFailureError('create worktree', resolved.registrationError);
  }
  throw new Error(
    'Cannot create worktree: not in a git repository.\n' +
      'Run from within a git repo, or use --no-worktree to skip isolation.'
  );
}

/** The refusal when `--resume` finds nothing to continue. */
function buildNoResumableRunError(workflowName: string, cwd: string): Error {
  return new Error(`No resumable run found for workflow '${workflowName}' at path '${cwd}'.`);
}

/** The refusal when the resumable-run lookup itself could not answer. */
function buildResumeLookupFailureError(error: Error): Error {
  return new Error(
    'Cannot resume: Database lookup failed.\n' +
      `Error: ${error.message}\n` +
      'Hint: Check your database connection before using --resume.'
  );
}

View on GitHub (pinned to 0773b97458)