thedotmack/claude-mem · error · Error

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

Second guard in assertServerRuntimeForCli(): after the runtime literal check passes, it requires a non-empty CLAUDE_MEM_SERVER_DATABASE_URL because every `server <cmd>` subcommand talks directly to the server's Postgres backend. It fails fast with this message instead of letting a pg Pool fail later with an unreadable connection error.

Solutions

  1. Export CLAUDE_MEM_SERVER_DATABASE_URL with the server Postgres connection string before running the command.
  2. Copy the exact value the running server container uses (docker inspect / compose env) so the CLI sees the same database.
  3. Put the export in the shell profile or a dedicated env file sourced before server admin sessions.

Example fix

# before
export CLAUDE_MEM_RUNTIME=server
claude-mem server api-key create
# -> CLAUDE_MEM_SERVER_DATABASE_URL is required

# after
export CLAUDE_MEM_RUNTIME=server
export CLAUDE_MEM_SERVER_DATABASE_URL=postgres://user:pass@host:5432/claude_mem
claude-mem server api-key create
Defensive patterns

Strategy: validation

Validate before calling

if (!(process.env.CLAUDE_MEM_SERVER_DATABASE_URL ?? '').trim()) {
  throw new Error(
    'CLAUDE_MEM_SERVER_DATABASE_URL is required for server CLI commands; ' +
    'export the Postgres connection string first',
  );
}

Prevention

When it happens

Trigger: Running `claude-mem server api-key ...` or another server subcommand with CLAUDE_MEM_RUNTIME=server set but no Postgres connection string exported; the variable present but whitespace-only; the connection string living only in the server's deployment environment rather than the operator's shell.

Common situations: First-time server setup where the database was provisioned but the env var never exported locally; running admin commands from a laptop while the URL exists only in the container/compose environment; quoting mistakes that leave the variable empty.

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@8bc631a71a (2026-08-20). Data as JSON: /api/errors/79c4b89a3ecc1870. 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 8bc631a71a)