{"record":{"id":"5a848c1dafc98a38","repo":"thedotmack/claude-mem","slug":"server-startup-configuration-is-invalid-lin","errorCode":null,"errorMessage":"server startup configuration is invalid:\n  - ${line}","messagePattern":"server startup configuration is invalid:\n  - (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/server/runtime/create-server-service.ts","lineNumber":144,"sourceCode":"    }\n  }\n\n  const hasDatabaseUrl = Boolean((env.CLAUDE_MEM_SERVER_DATABASE_URL ?? '').trim());\n  if (!hasDatabaseUrl) {\n    errors.push('CLAUDE_MEM_SERVER_DATABASE_URL is required to start the server (Postgres connection string).');\n  }\n\n  const hasRedisUrl = Boolean((env.CLAUDE_MEM_REDIS_URL ?? '').trim());\n  if (queueEngine === 'bullmq' && !hasRedisUrl) {\n    errors.push('CLAUDE_MEM_REDIS_URL is required when CLAUDE_MEM_QUEUE_ENGINE=bullmq.');\n  }\n\n  if (errors.length > 0) {\n    const message = [\n      'server startup configuration is invalid:',\n      ...errors.map(line => `  - ${line}`),\n    ].join('\\n');\n    throw new Error(message);\n  }\n\n  return {\n    isDocker,\n    // Phase 1a: report the canonical `'server'` value when unset; legacy\n    // `'server-beta'` is preserved verbatim when explicitly supplied so\n    // diagnostics reflect the operator's actual config.\n    runtime: runtime || 'server',\n    authMode,\n    queueEngine: queueEngine || 'disabled',\n    hasDatabaseUrl,\n    hasRedisUrl,\n  };\n}\n\n// #2443 — the server runtime must load an observation mode before it can\n// process any generation job; without it every job fails with \"No mode\n// loaded\". We mirror the worker's pattern (src/services/worker-service.ts) and","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/thedotmack/claude-mem/blob/e2d1df569a8f04075d40e92461128ece7cf04c82/src/server/runtime/create-server-service.ts#L126-L162","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read each '  - ' bullet line in order — every line names the exact variable and the accepted value; fix them all before restarting.","In Docker set CLAUDE_MEM_QUEUE_ENGINE=bullmq and provide CLAUDE_MEM_REDIS_URL (containers cannot use the in-process sqlite queue across boundaries).","Set CLAUDE_MEM_SERVER_DATABASE_URL to the Postgres connection string in every environment.","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`."],"exampleFix":"# before (docker-compose)\nenvironment:\n  CLAUDE_MEM_AUTH_MODE: local-dev\n  CLAUDE_MEM_SERVER_DATABASE_URL: postgres://...\n\n# after\nenvironment:\n  CLAUDE_MEM_RUNTIME: server\n  CLAUDE_MEM_AUTH_MODE: api-key\n  CLAUDE_MEM_QUEUE_ENGINE: bullmq\n  CLAUDE_MEM_REDIS_URL: rediss://default:pass@redis-host:6379\n  CLAUDE_MEM_SERVER_DATABASE_URL: postgres://...","handlingStrategy":"validation","validationCode":"import { validateServerEnv } from './create-server-service.js';\n\n// Fail with the full bullet list before booting anything else:\ntry {\n  validateServerEnv();\n} catch (e) {\n  console.error(e instanceof Error ? e.message : e);\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run env validation as the first step of every deploy so all bullets surface at once.","In Docker always set: CLAUDE_MEM_RUNTIME=server, CLAUDE_MEM_QUEUE_ENGINE=bullmq, CLAUDE_MEM_REDIS_URL, CLAUDE_MEM_SERVER_DATABASE_URL.","Never ship CLAUDE_MEM_AUTH_MODE=local-dev or CLAUDE_MEM_ALLOW_LOCAL_DEV_BYPASS into container images.","Template docker-compose/compose files from one validated source of truth so the required set stays in sync."],"tags":["configuration","startup","docker","env-var","validation","server"],"backgroundTag":"startup-config-validation","analyzedSha":"e2d1df569a8f04075d40e92461128ece7cf04c82","analyzedAt":"2026-08-20T23:58:13.836Z","contentChangedAt":"2026-08-20T23:58:13.836Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}