coleam00/Archon · critical · Error

Failed to access database: ${err.message} Hint: Check that D

Error message

Failed to access database: ${err.message}
Hint: Check that DATABASE_URL is set and the database is running.

What it means

The Archon CLI wraps all database failures from `conversationDb.getOrCreateConversation` into this error when pre-creating the workflow run row for a detached (background) launch. The library throws it because a detached run must have a queryable run row before forking, and that row needs a conversation record in the database. The original error's message is preserved verbatim; the hint points at the two usual causes: DATABASE_URL unset or the database process down.

Source

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

      if (resumeLookupError) throw buildResumeLookupFailureError(resumeLookupError);
      if (!continuationRun) throw buildNoResumableRunError(workflowName, cwd);
      detachedRunId = continuationRun.id;
    } else {
      // `Started` must mean a queryable run, so the row is written before the fork and
      // the child executes it rather than creating its own. Modeled on the
      // orchestrator's pre-created row (dispatchBackgroundWorkflowOwned), including
      // the stamps the executor only writes when IT creates the row. `working_path` is
      // the one field this process cannot know — the child cuts the worktree — so it
      // stays null until the child fills it in (write-once in the store).
      let detachedConversation;
      try {
        detachedConversation = await conversationDb.getOrCreateConversation(
          'cli',
          childConversationId
        );
      } catch (error) {
        const err = error as Error;
        throw new Error(
          `Failed to access database: ${err.message}\nHint: Check that DATABASE_URL is set and the database is running.`
        );
      }
      const detachedUserId = await resolveCliUserRecordId();
      const continuationDeclaration =
        adoptedRunId !== undefined
          ? { mode: 'adopt' as const, runId: adoptedRunId }
          : supersededRunId !== undefined
            ? { mode: 'supersede' as const, runId: supersededRunId }
            : undefined;
      try {
        // No reserved id: this process's own capture is discarded on the way out, and
        // reusing its id would point the child's capture at a directory this process is
        // about to reclaim. The row's generated id is what the child files under.
        const created = await workflowDb.createWorkflowRun({
          workflow_name: workflow.name,
          conversation_id: detachedConversation.id,
          ...(detachCodebase ? { codebase_id: detachCodebase.id } : {}),

View on GitHub (pinned to 0773b97458)

Solutions

Set DATABASE_URL in the environment or .env before running the command.
Start the database (e.g. docker compose up for the Postgres service) and verify connectivity.
Test the connection with a quick query (psql "$DATABASE_URL" -c 'select 1') to confirm credentials and host.
Run database initialization/migrations if the database is reachable but tables are missing.
Re-run the detached workflow launch.

Example fix

// before
archon workflow run my-flow --detach   # Failed to access database: ...
// after
export DATABASE_URL=postgres://user:pass@localhost:5432/archon
docker compose up -d db
archon workflow run my-flow --detach

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.DATABASE_URL) {
  throw new Error('DATABASE_URL is not set; configure it before detaching a workflow run.');
}
await db.execute(sql`select 1`); // connectivity probe before launch

Try / catch

try {
  await conversationDb.getOrCreateConversation('cli', id);
} catch (error) {
  const err = error as Error;
  console.error(`Database unavailable: ${err.message}. Check DATABASE_URL and that the server is running.`);
  process.exit(1);
}

Prevention

Always export DATABASE_URL in shell profiles or commit a checked .env template.
Add a health-check command to your session startup before running Archon commands.
Keep the database container in a compose service with a restart policy.
Run `archon` commands from the workspace directory so env loading applies.

When it happens

Trigger: Running `archon workflow run ... --detach` where getOrCreateConversation throws: DATABASE_URL is not set in the environment, the PostgreSQL/SQLite server is unreachable, credentials are wrong, or the schema/database has not been initialized.

Common situations: Fresh clone without a configured .env; Docker database container stopped; pointing at a host/port that is wrong after switching environments; running the CLI outside the workspace where env loading does not restore DATABASE_URL.

Related errors

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