{"record":{"id":"617c76e37399c96b","repo":"thedotmack/claude-mem","slug":"invalid-claude-mem-queue-engine-raw-expected-s","errorCode":null,"errorMessage":"Invalid CLAUDE_MEM_QUEUE_ENGINE=${raw}; expected sqlite or bullmq","messagePattern":"Invalid CLAUDE_MEM_QUEUE_ENGINE=(.+?); expected sqlite or bullmq","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/server/queue/redis-config.ts","lineNumber":27,"sourceCode":"export type ObservationQueueEngineName = 'sqlite' | 'bullmq';\nexport type RedisMode = 'external' | 'managed' | 'docker';\n\nexport interface RedisQueueConfig {\n  engine: ObservationQueueEngineName;\n  mode: RedisMode;\n  url: string | null;\n  host: string;\n  port: number;\n  prefix: string;\n  connection: RedisOptions;\n}\n\nexport function getObservationQueueEngineName(): ObservationQueueEngineName {\n  const raw = getQueueSetting('CLAUDE_MEM_QUEUE_ENGINE').trim().toLowerCase();\n  if (raw === 'sqlite' || raw === 'bullmq') {\n    return raw;\n  }\n  throw new Error(`Invalid CLAUDE_MEM_QUEUE_ENGINE=${raw}; expected sqlite or bullmq`);\n}\n\nexport function getRedisQueueConfig(): RedisQueueConfig {\n  const engine = getObservationQueueEngineName();\n  const mode = normalizeRedisMode(getQueueSetting('CLAUDE_MEM_REDIS_MODE'));\n  const url = getQueueSetting('CLAUDE_MEM_REDIS_URL').trim() || null;\n  const host = getQueueSetting('CLAUDE_MEM_REDIS_HOST').trim() || '127.0.0.1';\n  const port = parseRedisPort(getQueueSetting('CLAUDE_MEM_REDIS_PORT'));\n  const prefix = sanitizePrefix(getQueueSetting('CLAUDE_MEM_QUEUE_REDIS_PREFIX'));\n  const connection = url ? connectionFromUrl(url) : connectionFromHost(host, port);\n\n  return {\n    engine,\n    mode,\n    url,\n    host: url ? describeUrlHost(url).host : host,\n    port: url ? describeUrlHost(url).port : port,\n    prefix,","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/thedotmack/claude-mem/blob/d768ba364302d12b76e69e4f021f0bb1d2d50ed6/src/server/queue/redis-config.ts#L9-L45","documentation":"Thrown by getObservationQueueEngineName() when CLAUDE_MEM_QUEUE_ENGINE (read via getQueueSetting, trimmed, lowercased) is neither 'sqlite' nor 'bullmq'. An empty value is NOT accepted here — the function requires an explicit, valid engine name. This chooses which queue backend the worker/server uses.","triggerScenarios":"CLAUDE_MEM_QUEUE_ENGINE is set to a typo (e.g. 'redis', 'sql', 'postgres'), a legacy/deprecated name, or left empty when this code path requires a decision.","commonSituations":"Operator sets CLAUDE_MEM_QUEUE_ENGINE=redis thinking that is valid. A stale config from an older version. An unset value when getObservationQueueEngineName is called without a defaulting wrapper.","solutions":["Set CLAUDE_MEM_QUEUE_ENGINE to exactly 'sqlite' or 'bullmq'.","For server/Docker deployments use 'bullmq' (with CLAUDE_MEM_REDIS_URL set).","For single-process/local use choose 'sqlite'.","Remove the variable only if the calling path supplies its own default; otherwise set it explicitly."],"exampleFix":"// before: export CLAUDE_MEM_QUEUE_ENGINE=redis\n// after (server): export CLAUDE_MEM_QUEUE_ENGINE=bullmq\n// after (local): export CLAUDE_MEM_QUEUE_ENGINE=sqlite","handlingStrategy":"validation","validationCode":"function resolveQueueEngine(): 'sqlite' | 'bullmq' {\n  const raw = (process.env.CLAUDE_MEM_QUEUE_ENGINE ?? '').trim().toLowerCase();\n  if (raw !== 'sqlite' && raw !== 'bullmq') {\n    throw new Error('Set CLAUDE_MEM_QUEUE_ENGINE to sqlite or bullmq');\n  }\n  return raw;\n}","typeGuard":"function isQueueEngineName(v: string): v is 'sqlite' | 'bullmq' {\n  return v === 'sqlite' || v === 'bullmq';\n}","tryCatchPattern":"try {\n  engine = getObservationQueueEngineName();\n} catch (error) {\n  // print guidance and exit; do not default silently\n  console.error((error as Error).message);\n  process.exit(1);\n}","preventionTips":["Set CLAUDE_MEM_QUEUE_ENGINE explicitly to sqlite or bullmq in every environment.","Add a startup config lint that rejects typos before the server boots."],"tags":["config","queue","env","validation"],"backgroundTag":null,"analyzedSha":"d768ba364302d12b76e69e4f021f0bb1d2d50ed6","analyzedAt":"2026-08-12T23:52:55.241Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}