coleam00/Archon · error · Error

Cannot create worktree: database lookup failed. Error: ${res

Error message

Cannot create worktree: database lookup failed.
Error: ${resolved.lookupError.message}
Hint: Check your database connection, or use --no-worktree to skip isolation.

What it means

assertCodebaseResolvedForIsolation() gates worktree isolation on the codebase having been resolved from the database. When getCodebase returned no codebase AND an explicit lookupError was captured (as opposed to 'simply not registered'), the CLI throws this refusal rather than attempting worktree creation against unknown repository state. The original DB error message and an actionable hint are embedded.

Source

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

/**
 * Refuse an isolated run that has no project to isolate, naming which step failed.
 *
 * One owner because two callers enforce the same policy at different times: the
 * `--detach` pre-flight, which must refuse before the fork (#2872), and the isolation
 * block, which is where a foreground run reaches it. Two copies of this decision is
 * exactly how the detached path came to skip it.
 *
 * A no-op once a codebase resolved — the isolation block only reaches it with none, and
 * 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}'.`);
}

View on GitHub (pinned to 0773b97458)

Solutions

Check your database connection (DSN in config, server reachable, SQLite file present).
If worktree isolation is not needed, re-run with --no-worktree to skip isolation.
Inspect the embedded Error message — it carries the original database failure.
Restart the database service or fix file permissions, then retry the run.

Example fix

// before: DSN points at a stopped server
$ archon workflow run foo
Error: Cannot create worktree: database lookup failed.
Error: connect ECONNREFUSED 127.0.0.1:5432
// after: start the DB or point the DSN at a live server
$ docker start archon-postgres && archon workflow run foo

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-flight: confirm the database is reachable before starting an isolated run
import { getDatabase } from '@archon/core';
try {
  await getDatabase().query('SELECT 1');
} catch (e) {
  console.error('DB unreachable; fix the connection or plan to use --no-worktree');
}

Try / catch

try {
  await runWorkflow(name, opts);
} catch (e) {
  const msg = String((e as Error).message);
  if (msg.includes('database lookup failed')) {
    console.error('Fix DB connectivity or retry with --no-worktree:', msg);
  }
}

Prevention

Verify the DSN / SQLite path before launching runs (`archon doctor` or a SELECT 1 probe).
Keep the SQLite file on writable local storage; avoid moving it between runs.
Monitor database availability for remote Postgres installs.
Use --no-worktree when isolation is unnecessary and the DB is known-flaky.

When it happens

Trigger: runWorkflowWithOwnedSource calls the resolver, codebaseDb.getCodebase throws (connection failure, DB locked, adapter crash), resolved.codebase stays null and resolved.lookupError is set; the check then throws during worktree pre-flight.

Common situations: SQLite file moved/missing or unreadable; Postgres DSN wrong or server down; permissions on the DB file; database locked by another process; transient network outage to a remote Postgres.

Related errors

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