CLAUDE_MEM_SERVER_DATABASE_URL is required for \`server

Error message

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.

What it means

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.

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

Example fix

// before
CLAUDE_MEM_RUNTIME=server server jobs list
// after
CLAUDE_MEM_RUNTIME=server CLAUDE_MEM_SERVER_DATABASE_URL=postgres://user:pass@host:5432/claude_mem server jobs list

Defensive patterns

Strategy: validation

Validate before calling

if (!(process.env.CLAUDE_MEM_SERVER_DATABASE_URL ?? '').trim()) {
  console.error('CLAUDE_MEM_SERVER_DATABASE_URL is required for server CLI commands');
  process.exit(1);
}

Type guard

function hasServerDbUrl(env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & { CLAUDE_MEM_SERVER_DATABASE_URL: string } {
  return Boolean((env.CLAUDE_MEM_SERVER_DATABASE_URL ?? '').trim());
}

Try / catch

try {
  runServerJobsCli(argv);
} catch (e) {
  if (String(e.message).includes('CLAUDE_MEM_SERVER_DATABASE_URL is required')) {
    console.error('Export CLAUDE_MEM_SERVER_DATABASE_URL with the server Postgres connection string.');
    process.exit(1);
  }
  throw e;
}

Prevention

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

When it happens

Trigger: Running a server CLI command (runServerApiKeyCli/runServerJobsCli) in the server runtime with CLAUDE_MEM_SERVER_DATABASE_URL unset or whitespace-only.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of thedotmack/claude-mem@d8bc9755e7 (2026-09-17). Data as JSON: /api/errors/317f58b864ddbfa9. Report an issue: GitHub.

Appendix: source

Thrown at src/server/runtime/ServerService.ts:500

// or no `CLAUDE_MEM_SERVER_DATABASE_URL` configured — we fail fast with an
// actionable message instead of crashing later with an opaque pool error.
//
// Phase 1d: dual-accept the persisted runtime literal (`'server'` is the new
// canonical form; `'server-beta'` remains valid for existing installs).
export function assertServerRuntimeForCli(
  commandLabel: string,
  env: NodeJS.ProcessEnv = process.env,
): void {
  const runtime = (env.CLAUDE_MEM_RUNTIME ?? '').trim().toLowerCase();
  if (runtime && runtime !== 'server' && runtime !== 'server-beta') {
    throw new Error(
      `\`server ${commandLabel}\` is a server runtime command, but CLAUDE_MEM_RUNTIME=${runtime}. ` +
        'Set CLAUDE_MEM_RUNTIME=server (and CLAUDE_MEM_SERVER_DATABASE_URL) to run server operations, ' +
        'or use the worker CLI (`worker-service ...`) for the worker runtime.',
    );
  }
  if (!(env.CLAUDE_MEM_SERVER_DATABASE_URL ?? '').trim()) {
    throw new Error(
      `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.',
    );
  }
}

export async function runServerApiKeyCli(argv: string[]): Promise<void> {
  const sub = argv[0]?.toLowerCase();
  const options = parseFlagArgs(argv.slice(1));

  try {
    assertServerRuntimeForCli('api-key');
  } catch (error) {
    console.error(error instanceof Error ? error.message : String(error));
    process.exit(1);
  }

  // #2560 — `api-key migrate-scopes <id>` brings a key's scope set up to a

View on GitHub (pinned to d8bc9755e7)