{"record":{"id":"317f58b864ddbfa9","repo":"thedotmack/claude-mem","slug":"claude-mem-server-database-url-is-required-for-server","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":500,"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":482,"sourceCodeEnd":518,"githubUrl":"https://github.com/thedotmack/claude-mem/blob/d8bc9755e74915e5c3b999181e10a67c889bce2a/src/server/runtime/ServerService.ts#L482-L518","documentation":"After passing the runtime check, assertServerRuntimeForCli verifies CLAUDE_MEM_SERVER_DATABASE_URL is set; server CLI commands talk directly to the server Postgres backend and cannot run without a connection string. It throws when the variable is missing or blank.","triggerScenarios":"Running a server CLI command (runServerApiKeyCli/runServerJobsCli) in the server runtime with CLAUDE_MEM_SERVER_DATABASE_URL unset or whitespace-only.","commonSituations":"Fresh developer machines or new CI jobs where only CLAUDE_MEM_RUNTIME was configured; .env files not loaded by the CLI entrypoint; the connection string exported under a differently named variable.","solutions":["Export CLAUDE_MEM_SERVER_DATABASE_URL with the server Postgres connection string before running the command","Ensure your shell/.env actually loads that variable (check with `printenv CLAUDE_MEM_SERVER_DATABASE_URL`)","Verify the variable name — it must be CLAUDE_MEM_SERVER_DATABASE_URL, not a legacy/different name"],"exampleFix":"// before\nCLAUDE_MEM_RUNTIME=server server jobs list\n// after\nCLAUDE_MEM_RUNTIME=server CLAUDE_MEM_SERVER_DATABASE_URL=postgres://user:pass@host:5432/claude_mem server jobs list","handlingStrategy":"validation","validationCode":"if (!(process.env.CLAUDE_MEM_SERVER_DATABASE_URL ?? '').trim()) {\n  console.error('CLAUDE_MEM_SERVER_DATABASE_URL is required for server CLI commands');\n  process.exit(1);\n}","typeGuard":"function hasServerDbUrl(env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & { CLAUDE_MEM_SERVER_DATABASE_URL: string } {\n  return Boolean((env.CLAUDE_MEM_SERVER_DATABASE_URL ?? '').trim());\n}","tryCatchPattern":"try {\n  runServerJobsCli(argv);\n} catch (e) {\n  if (String(e.message).includes('CLAUDE_MEM_SERVER_DATABASE_URL is required')) {\n    console.error('Export CLAUDE_MEM_SERVER_DATABASE_URL with the server Postgres connection string.');\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Set CLAUDE_MEM_SERVER_DATABASE_URL in .env and ensure the CLI loads it before parsing commands","Verify required env at script start with a fail-fast check","Export it in CI/deployment templates for server roles","Use consistent variable naming to avoid shadowing by legacy DB URL vars"],"tags":["env","postgres","cli"],"backgroundTag":"missing-env-var","analyzedSha":"d8bc9755e74915e5c3b999181e10a67c889bce2a","analyzedAt":"2026-09-17T16:40:26.182Z","contentChangedAt":"2026-09-17T16:40:26.182Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}