Failed to bootstrap server API key: ${error instanceof Error

Error message

Failed to bootstrap server API key: ${error instanceof Error ? error.message : String(error)}. Hooks will fall back to the worker until you run `npx claude-mem server keys rotate`.

What it means

A log.warn from the installer's server-key bootstrap: bootstrapAndPersistServerApiKey() rejected. This step provisions an API key for hooks against the claude-mem server, which requires CLAUDE_MEM_SERVER_DATABASE_URL (Postgres) to be set — without it the function isn't even attempted. On failure the installer states the degraded mode explicitly: hooks fall back to talking to the local worker until a key is provisioned via `npx claude-mem server keys rotate`.

Source

Thrown at src/npx-cli/commands/install.ts:1004

  await maybeBootstrapServerApiKey();
}

async function maybeBootstrapServerApiKey(): Promise<void> {
  // Only attempt if Postgres is configured. Without DATABASE_URL we cannot
  // reach the api_keys table — the operator must configure the server first
  // and rerun `claude-mem server keys rotate`.
  if (!process.env.CLAUDE_MEM_SERVER_DATABASE_URL) {
    log.warn(
      'Skipping local hook API key bootstrap: CLAUDE_MEM_SERVER_DATABASE_URL is not set. '
        + 'Run `npx claude-mem server keys rotate` after configuring Postgres to provision a key.',
    );
    return;
  }
  try {
    await bootstrapAndPersistServerApiKey();
  } catch (error: unknown) {
    // [ANTI-PATTERN IGNORED]: the failure is already surfaced to the user via the interactive-aware log.warn wrapper below (p.log.warn in a TTY, console.warn otherwise), including the manual remediation command.
    log.warn(
      `Failed to bootstrap server API key: ${error instanceof Error ? error.message : String(error)}. `
        + 'Hooks will fall back to the worker until you run `npx claude-mem server keys rotate`.',
    );
  }
}

async function bootstrapAndPersistServerApiKey(): Promise<void> {
  const { bootstrapServerApiKey, persistServerSettings } = await import(
    '../../services/hooks/server-bootstrap.js'
  );
  const result = await bootstrapServerApiKey();
  persistServerSettings(USER_SETTINGS_PATH, {
    apiKey: result.rawKey,
    projectId: result.projectId,
  });
  log.info(
    `Provisioned local hook API key (project=${result.projectId.slice(0, 8)}…). `
      + 'Settings saved with mode 0600.',

View on GitHub (pinned to 8bc631a71a)

Solutions

Finish setup later with the documented command: npx claude-mem server keys rotate
Verify prerequisites first: CLAUDE_MEM_SERVER_DATABASE_URL is set, Postgres accepts connections, migrations ran
Until the key exists, expect hooks to use the local-worker fallback — data still flows, server-mode features do not

Example fix

# before
[warn] Failed to bootstrap server API key: fetch failed. Hooks will fall back…

# after
$ psql "$CLAUDE_MEM_SERVER_DATABASE_URL" -c 'select 1'   # confirm DB reachable
$ npx claude-mem server keys rotate                        # provision the key

Defensive patterns

Strategy: retry

Validate before calling

function serverBootstrapPreconditions(): string | null {
  if (!process.env.CLAUDE_MEM_SERVER_DATABASE_URL)
    return 'CLAUDE_MEM_SERVER_DATABASE_URL not set — bootstrap is skipped by design';
  return null;
}

Try / catch

try {
  await bootstrapAndPersistServerApiKey();
} catch (e) {
  log.warn(`key bootstrap failed (${msg(e)}); run \`npx claude-mem server keys rotate\` after Postgres is up`);
}

Prevention

Bring Postgres up and verified (select 1) before running install with server env vars set
Always finish server-mode setup with `npx claude-mem server keys rotate` if bootstrap warned
Remember the documented fallback: without a key, hooks talk to the local worker — nothing is lost locally

When it happens

Trigger: Installing with CLAUDE_MEM_SERVER_DATABASE_URL set but Postgres unreachable, credentials wrong, the database not migrated, or the bootstrap HTTP call to the server failing/timeout; partially configured server environments.

Common situations: Server-mode adopters who set the env var before the Postgres instance or the claude-mem server itself is running; rotated/dropped database credentials; connecting to a server URL that is behind a proxy returning an error page.

Related errors

AI-assisted analysis of thedotmack/claude-mem@8bc631a71a (2026-08-20). Data as JSON: /api/errors/3e55a4cd0af1ef8e. Report an issue: GitHub.