thedotmack/claude-mem · critical · Error

server startup configuration is invalid

Error message

server startup configuration is invalid:
  - ${line}

What it means

validateServerEnv() in create-server-service.ts aggregates every startup misconfiguration into one Error whose message lists each problem as a bullet line. Checks include: runtime literal validity inside Docker, auth mode and loopback-bypass restrictions in Docker, CLAUDE_MEM_QUEUE_ENGINE presence/value in Docker, a required CLAUDE_MEM_SERVER_DATABASE_URL, and CLAUDE_MEM_REDIS_URL presence when the engine is bullmq. The server refuses to boot until all bullets are fixed.

Solutions

  1. Read each ' - ' bullet line in order — every line names the exact variable and the accepted value; fix them all before restarting.
  2. In Docker set CLAUDE_MEM_QUEUE_ENGINE=bullmq and provide CLAUDE_MEM_REDIS_URL (containers cannot use the in-process sqlite queue across boundaries).
  3. Set CLAUDE_MEM_SERVER_DATABASE_URL to the Postgres connection string in every environment.
  4. Remove CLAUDE_MEM_AUTH_MODE=local-dev and CLAUDE_MEM_ALLOW_LOCAL_DEV_BYPASS in Docker; use api-key auth and create a key with `claude-mem server api-key create`.

Example fix

# before (docker-compose)
environment:
  CLAUDE_MEM_AUTH_MODE: local-dev
  CLAUDE_MEM_SERVER_DATABASE_URL: postgres://...

# after
environment:
  CLAUDE_MEM_RUNTIME: server
  CLAUDE_MEM_AUTH_MODE: api-key
  CLAUDE_MEM_QUEUE_ENGINE: bullmq
  CLAUDE_MEM_REDIS_URL: rediss://default:pass@redis-host:6379
  CLAUDE_MEM_SERVER_DATABASE_URL: postgres://...
Defensive patterns

Strategy: validation

Validate before calling

import { validateServerEnv } from './create-server-service.js';

// Fail with the full bullet list before booting anything else:
try {
  validateServerEnv();
} catch (e) {
  console.error(e instanceof Error ? e.message : e);
  process.exit(1);
}

Prevention

When it happens

Trigger: Starting the server container with CLAUDE_MEM_RUNTIME=worker; enabling CLAUDE_MEM_AUTH_MODE=local-dev or CLAUDE_MEM_ALLOW_LOCAL_DEV_BYPASS inside Docker (both forbidden in containers because loopback bypass cannot be enforced there); omitting CLAUDE_MEM_QUEUE_ENGINE in Docker or setting it to sqlite; missing CLAUDE_MEM_SERVER_DATABASE_URL; choosing queue engine bullmq without a CLAUDE_MEM_REDIS_URL.

Common situations: Porting a working local (non-Docker) env file into a container where stricter rules apply; docker-compose files that only set the database URL; disabling auth for quick local testing and then shipping the same config to Docker; enabling bullmq but forgetting Redis credentials.

Related errors

AI-assisted analysis of thedotmack/claude-mem@e2d1df569a (2026-08-20). Data as JSON: /api/errors/5a848c1dafc98a38. Report an issue: GitHub.

Appendix: source

Thrown at src/server/runtime/create-server-service.ts:144

    }
  }

  const hasDatabaseUrl = Boolean((env.CLAUDE_MEM_SERVER_DATABASE_URL ?? '').trim());
  if (!hasDatabaseUrl) {
    errors.push('CLAUDE_MEM_SERVER_DATABASE_URL is required to start the server (Postgres connection string).');
  }

  const hasRedisUrl = Boolean((env.CLAUDE_MEM_REDIS_URL ?? '').trim());
  if (queueEngine === 'bullmq' && !hasRedisUrl) {
    errors.push('CLAUDE_MEM_REDIS_URL is required when CLAUDE_MEM_QUEUE_ENGINE=bullmq.');
  }

  if (errors.length > 0) {
    const message = [
      'server startup configuration is invalid:',
      ...errors.map(line => `  - ${line}`),
    ].join('\n');
    throw new Error(message);
  }

  return {
    isDocker,
    // Phase 1a: report the canonical `'server'` value when unset; legacy
    // `'server-beta'` is preserved verbatim when explicitly supplied so
    // diagnostics reflect the operator's actual config.
    runtime: runtime || 'server',
    authMode,
    queueEngine: queueEngine || 'disabled',
    hasDatabaseUrl,
    hasRedisUrl,
  };
}

// #2443 — the server runtime must load an observation mode before it can
// process any generation job; without it every job fails with "No mode
// loaded". We mirror the worker's pattern (src/services/worker-service.ts) and

View on GitHub (pinned to e2d1df569a)