{"record":{"id":"d0175def8ba36445","repo":"coleam00/Archon","slug":"failed-to-access-database-err-message-hint-ch","errorCode":null,"errorMessage":"Failed to access database: ${err.message}\nHint: Check that DATABASE_URL is set and the database is running.","messagePattern":"Failed to access database: (.+?)\nHint: Check that DATABASE_URL is set and the database is running\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/cli/src/commands/workflow.ts","lineNumber":2097,"sourceCode":"      if (resumeLookupError) throw buildResumeLookupFailureError(resumeLookupError);\n      if (!continuationRun) throw buildNoResumableRunError(workflowName, cwd);\n      detachedRunId = continuationRun.id;\n    } else {\n      // `Started` must mean a queryable run, so the row is written before the fork and\n      // the child executes it rather than creating its own. Modeled on the\n      // orchestrator's pre-created row (dispatchBackgroundWorkflowOwned), including\n      // the stamps the executor only writes when IT creates the row. `working_path` is\n      // the one field this process cannot know — the child cuts the worktree — so it\n      // stays null until the child fills it in (write-once in the store).\n      let detachedConversation;\n      try {\n        detachedConversation = await conversationDb.getOrCreateConversation(\n          'cli',\n          childConversationId\n        );\n      } catch (error) {\n        const err = error as Error;\n        throw new Error(\n          `Failed to access database: ${err.message}\\nHint: Check that DATABASE_URL is set and the database is running.`\n        );\n      }\n      const detachedUserId = await resolveCliUserRecordId();\n      const continuationDeclaration =\n        adoptedRunId !== undefined\n          ? { mode: 'adopt' as const, runId: adoptedRunId }\n          : supersededRunId !== undefined\n            ? { mode: 'supersede' as const, runId: supersededRunId }\n            : undefined;\n      try {\n        // No reserved id: this process's own capture is discarded on the way out, and\n        // reusing its id would point the child's capture at a directory this process is\n        // about to reclaim. The row's generated id is what the child files under.\n        const created = await workflowDb.createWorkflowRun({\n          workflow_name: workflow.name,\n          conversation_id: detachedConversation.id,\n          ...(detachCodebase ? { codebase_id: detachCodebase.id } : {}),","sourceCodeStart":2079,"sourceCodeEnd":2115,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/cli/src/commands/workflow.ts#L2079-L2115","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\narchon workflow run my-flow --detach   # Failed to access database: ...\n// after\nexport DATABASE_URL=postgres://user:pass@localhost:5432/archon\ndocker compose up -d db\narchon workflow run my-flow --detach","handlingStrategy":"validation","validationCode":"if (!process.env.DATABASE_URL) {\n  throw new Error('DATABASE_URL is not set; configure it before detaching a workflow run.');\n}\nawait db.execute(sql`select 1`); // connectivity probe before launch","typeGuard":null,"tryCatchPattern":"try {\n  await conversationDb.getOrCreateConversation('cli', id);\n} catch (error) {\n  const err = error as Error;\n  console.error(`Database unavailable: ${err.message}. Check DATABASE_URL and that the server is running.`);\n  process.exit(1);\n}","preventionTips":["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."],"tags":["database","cli","configuration","environment"],"backgroundTag":"missing-database-url","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}