Cannot ${action}: repository registration failed. Error: ${e

Error message

Cannot ${action}: repository registration failed.
Error: ${error.message}
${hint} (action='resume'; hint is 'Hint: Remove the stale workspace entry at ${staleWorkspaceEntry} and retry, or use --no-worktree to skip isolation.' or 'Hint: Check your Archon workspace registration under ${workspacesPath} and retry, or use --no-worktree to skip isolation.')

What it means

With --resume and no resolved codebase, if the codebase lookup succeeded but workspace/repository registration failed, the CLI throws buildRegistrationFailureError('resume', codebaseRegistrationError): 'Cannot resume: repository registration failed.\nError: <detail>\n' followed by a hint. The hint is either 'Remove the stale workspace entry at <staleWorkspaceEntry> and retry, or use --no-worktree to skip isolation.' or 'Check your Archon workspace registration under <workspacesPath> and retry, or use --no-worktree to skip isolation.' depending on whether a stale workspace entry was detected.

Source

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

      console.log(`Superseding run ${superseded.id} — fresh lane, provenance recorded.`);
    }
  }

  // Handle --resume: locate the prior failed run, reuse its worktree, and hand
  // the resumed-run handle to executeWorkflow below via opts. The executor no
  // longer performs implicit resume detection on its own.
  let resumable: WorkflowRun | null = null;
  if (options.resume) {
    if (!codebase) {
      if (codebaseLookupError) {
        throw new Error(
          'Cannot resume: Database lookup failed.\n' +
            `Error: ${codebaseLookupError.message}\n` +
            'Hint: Check your database connection before using --resume.'
        );
      }
      if (codebaseRegistrationError) {
        throw buildRegistrationFailureError('resume', codebaseRegistrationError);
      }
      throw new Error(
        'Cannot resume: Not in a git repository.\n' +
          'Either run from a git repo or use /clone first.'
      );
    }

    if (resumeLookupError) {
      throw buildResumeLookupFailureError(resumeLookupError);
    }
    // Resolved before discovery (top of this function), because the graph this run
    // executes had to be chosen from it.
    resumable = continuationRun ?? null;

    if (!resumable) {
      throw buildNoResumableRunError(workflowName, cwd);
    }

View on GitHub (pinned to 0773b97458)

Solutions

Follow the printed hint: remove the stale workspace entry file/directory at the given path and retry the --resume command
If the recorded workspace path is wrong, fix or remove the registration under the printed workspaces path
Use --no-worktree to skip isolation if you intend to resume in place
Verify the current directory is the registered git repository checkout

Example fix

// before
archon workflow run fix-issue --resume   // stale worktree entry
// after
rm -rf ~/.archon/workspaces/<stale-entry>
archon workflow run fix-issue --resume

Defensive patterns

Strategy: try-catch

Validate before calling

import { existsSync } from 'node:fs';
// before `run --resume`, ensure no stale workspace entries remain
const wsDir = join(home, '.archon', 'workspaces');
if (existsSync(wsDir)) {
  for (const entry of readdirSync(wsDir)) {
    const rec = JSON.parse(readFileSync(join(wsDir, entry), 'utf8'));
    if (!existsSync(rec.path)) console.warn(`stale workspace entry: ${join(wsDir, entry)}`);
  }
}

Try / catch

try {
  await runWorkflow(name, { resume: true });
} catch (e) {
  const m = String(e.message);
  if (m.includes('repository registration failed')) {
    const stale = m.match(/stale workspace entry at (\S+)/)?.[1];
    if (stale) rmSync(stale, { recursive: true, force: true });
    // else inspect the printed workspaces path; or retry with --no-worktree
  } else throw e;
}

Prevention

Never delete a run's worktree directory manually; let Archon clean it up or remove the matching workspace entry
Re-run registration after moving/renaming a checkout
Keep ~/.archon/workspace registry under version control awareness — inspect it before resuming
Use --no-worktree deliberately when resuming in place

When it happens

Trigger: Running `archon workflow run <name> --resume` where codebase is null, codebaseLookupError is null, but codebaseRegistrationError is set (workflow.ts:2369-2370) — resume requires the project identity, and registering the current git repository into the Archon workspace registry failed, e.g. because of a stale worktree/workspace entry or corrupt registration metadata under the workspaces path.

Common situations: Resuming after manually deleting a worktree directory that is still registered (stale entry); moving or renaming the checkout so the recorded path no longer matches; a corrupt ~/.archon workspace registry; conflicting registrations from parallel clones.

Related errors

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