{"record":{"id":"79c4b89a3ecc1870","repo":"thedotmack/claude-mem","slug":"claude-mem-server-database-url-is-required-for-se","errorCode":null,"errorMessage":"CLAUDE_MEM_SERVER_DATABASE_URL is required for `server ${commandLabel}`. This command talks to the server Postgres backend; export the connection string before running it.","messagePattern":"CLAUDE_MEM_SERVER_DATABASE_URL is required for `server (.+?)`\\. This command talks to the server Postgres backend; export the connection string before running it\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/server/runtime/ServerService.ts","lineNumber":460,"sourceCode":"// or no `CLAUDE_MEM_SERVER_DATABASE_URL` configured — we fail fast with an\n// actionable message instead of crashing later with an opaque pool error.\n//\n// Phase 1d: dual-accept the persisted runtime literal (`'server'` is the new\n// canonical form; `'server-beta'` remains valid for existing installs).\nexport function assertServerRuntimeForCli(\n  commandLabel: string,\n  env: NodeJS.ProcessEnv = process.env,\n): void {\n  const runtime = (env.CLAUDE_MEM_RUNTIME ?? '').trim().toLowerCase();\n  if (runtime && runtime !== 'server' && runtime !== 'server-beta') {\n    throw new Error(\n      `\\`server ${commandLabel}\\` is a server runtime command, but CLAUDE_MEM_RUNTIME=${runtime}. ` +\n        'Set CLAUDE_MEM_RUNTIME=server (and CLAUDE_MEM_SERVER_DATABASE_URL) to run server operations, ' +\n        'or use the worker CLI (`worker-service ...`) for the worker runtime.',\n    );\n  }\n  if (!(env.CLAUDE_MEM_SERVER_DATABASE_URL ?? '').trim()) {\n    throw new Error(\n      `CLAUDE_MEM_SERVER_DATABASE_URL is required for \\`server ${commandLabel}\\`. ` +\n        'This command talks to the server Postgres backend; export the connection string before running it.',\n    );\n  }\n}\n\nexport async function runServerApiKeyCli(argv: string[]): Promise<void> {\n  const sub = argv[0]?.toLowerCase();\n  const options = parseFlagArgs(argv.slice(1));\n\n  try {\n    assertServerRuntimeForCli('api-key');\n  } catch (error) {\n    console.error(error instanceof Error ? error.message : String(error));\n    process.exit(1);\n  }\n\n  // #2560 — `api-key migrate-scopes <id>` brings a key's scope set up to a","sourceCodeStart":442,"sourceCodeEnd":478,"githubUrl":"https://github.com/thedotmack/claude-mem/blob/d768ba364302d12b76e69e4f021f0bb1d2d50ed6/src/server/runtime/ServerService.ts#L442-L478","documentation":"Thrown by assertServerRuntimeForCli() when CLAUDE_MEM_SERVER_DATABASE_URL is empty/unset and a `server <command>` operation is invoked. Server CLI commands talk to the Postgres backend, so the connection string is mandatory. This is a fast-fail so the command doesn't proceed to an opaque pool/connection error.","triggerScenarios":"Running `claude-mem server <commandLabel>` (e.g. api-key, or any server-runtime operation) without CLAUDE_MEM_SERVER_DATABASE_URL exported; the variable is set but whitespace-only (it is trimmed before the check).","commonSituations":"Fresh server install where the operator hasn't configured the database yet. The variable was exported in a different shell/session. A typo in the variable name.","solutions":["Export CLAUDE_MEM_SERVER_DATABASE_URL to a valid Postgres connection string (postgres://user:pass@host:5432/db) before running the command.","Ensure the variable is set in the same shell/session that runs the CLI (or in the container env / systemd unit / .env loaded by the launcher).","Confirm the database is reachable and the user has the required privileges.","Set CLAUDE_MEM_RUNTIME=server alongside it if not already set."],"exampleFix":"// before: CLAUDE_MEM_SERVER_DATABASE_URL unset\n// after: export CLAUDE_MEM_SERVER_DATABASE_URL=postgres://app:secret@db:5432/claude_mem\n//        claude-mem server api-key create","handlingStrategy":"validation","validationCode":"function assertServerDatabaseUrl(env: NodeJS.ProcessEnv = process.env): void {\n  if (!(env.CLAUDE_MEM_SERVER_DATABASE_URL ?? '').trim()) {\n    throw new Error('Export CLAUDE_MEM_SERVER_DATABASE_URL (postgres://...) before running server commands');\n  }\n}","typeGuard":"function hasServerDatabaseUrl(env: NodeJS.ProcessEnv): boolean {\n  return Boolean((env.CLAUDE_MEM_SERVER_DATABASE_URL ?? '').trim());\n}","tryCatchPattern":"try {\n  assertServerRuntimeForCli('api-key');\n} catch (error) {\n  if (/CLAUDE_MEM_SERVER_DATABASE_URL is required/.test((error as Error).message)) {\n    console.error('Export CLAUDE_MEM_SERVER_DATABASE_URL before retrying.');\n    process.exit(1);\n  }\n  throw error;\n}","preventionTips":["Always export CLAUDE_MEM_SERVER_DATABASE_URL in any shell/container running server commands.","Put the variable in the launcher (systemd unit, Docker env, .env loaded by the app).","Confirm the Postgres user has the required privileges before first run."],"tags":["config","database","env","cli","postgres"],"backgroundTag":null,"analyzedSha":"d768ba364302d12b76e69e4f021f0bb1d2d50ed6","analyzedAt":"2026-08-12T23:52:55.241Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}