coleam00/Archon · critical · Error

Cannot resume: Database lookup failed. Error: ${codebaseLook

Error message

Cannot resume: Database lookup failed.
Error: ${codebaseLookupError.message}
Hint: Check your database connection before using --resume.

What it means

When --resume is requested but the codebase (project) could not be resolved because the database lookup itself failed, the CLI aborts with this error. Resume must find the prior run and its worktree via the database, so a broken DB connection makes resume impossible; the wrapped message carries the lookup error and the hint tells the user to fix the connection first.

Source

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

      } else {
        console.log(
          `Adopting run ${adoptedRun.id} — folder projects run in place; adoption carries provenance and $ADOPTED_RUN_DIR access only.`
        );
      }
    } else {
      const superseded = await resolveSupersededRun(adoptedFromRunId);
      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

View on GitHub (pinned to 0773b97458)

Solutions

Restore the database connection (start the server, fix DATABASE_URL).
Verify connectivity with a direct client before retrying --resume.
Run schema init/migrations if tables are missing.
Retry `--resume` once the lookup succeeds.
If the database is unrecoverable, start a fresh run instead of resuming.

Example fix

// before
archon workflow run my-flow --resume  # Cannot resume: Database lookup failed. Error: connect ECONNREFUSED
// after
docker compose up -d db && archon workflow run my-flow --resume

Defensive patterns

Strategy: validation

Validate before calling

// before --resume, probe the database
if (!process.env.DATABASE_URL) throw new Error('DATABASE_URL not set; --resume needs the DB.');
await db.execute(sql`select 1`);

Try / catch

try {
  await runWorkflow({ resume: true });
} catch (error) {
  const msg = (error as Error).message;
  if (msg.startsWith('Cannot resume: Database lookup failed.')) {
    console.error('Fix the DB connection (see embedded Error:) then retry --resume.');
  } else throw error;
}

Prevention

Verify DB connectivity before any resume operation.
Keep the database service running across dev sessions.
Run migrations after upgrades so lookups do not fail on missing tables.

When it happens

Trigger: Running `archon workflow run <flow> --resume` where resolveRunCodebase set lookupError — the database query for the project failed because the DB is down, DATABASE_URL is wrong, or the schema is missing.

Common situations: Postgres container stopped between runs; DATABASE_URL changed after switching from local to remote DB; first run after cloning without db init.

Related errors

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