{"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/d8bc9755e74915e5c3b999181e10a67c889bce2a/src/server/queue/redis-config.ts#L9-L45","documentation":"This error is thrown by getObservationQueueEngineName when the CLAUDE_MEM_QUEUE_ENGINE environment variable contains a value other than 'sqlite' or 'bullmq' (case-insensitive, after trimming). claude-mem uses this variable to select the observation queue backend, and it refuses to start with an unknown engine name rather than silently defaulting. The raw, unnormalized value is interpolated into the message so you can see exactly what was read.","triggerScenarios":"Setting CLAUDE_MEM_QUEUE_ENGINE to any string other than 'sqlite' or 'bullmq' — e.g. 'redis', 'sqlite3', 'SQLite ' is fine after trim/lowercase, but 'redis', '', a typo like 'bullm', or a quoted '\"sqlite\"' value all throw. Called indirectly whenever getRedisQueueConfig()/engine selection runs during queue initialization.","commonSituations":"Typo'ing the engine name in .env or docker-compose; copying config from an older version that allowed other engines; leaving the variable set to an empty or placeholder value like 'CHANGE_ME'; exporting it with surrounding quotes or whitespace embedded in the value from CI secret managers.","solutions":["Set CLAUDE_MEM_QUEUE_ENGINE=sqlite (default, no Redis needed) or CLAUDE_MEM_QUEUE_ENGINE=bullmq in your environment/.env","Remove surrounding quotes or stray whitespace from the value in .env / shell exports","If you meant to use Redis-based queuing, verify the exact spelling 'bullmq'","If the variable is not needed, unset it entirely so defaults apply"],"exampleFix":"// before (.env)\nCLAUDE_MEM_QUEUE_ENGINE=redis\n// after\nCLAUDE_MEM_QUEUE_ENGINE=bullmq","handlingStrategy":"validation","validationCode":"const ALLOWED = ['sqlite','bullmq'];\nconst raw = (process.env.CLAUDE_MEM_QUEUE_ENGINE ?? '').trim().toLowerCase();\nif (!ALLOWED.includes(raw)) {\n  throw new Error(`CLAUDE_MEM_QUEUE_ENGINE must be one of ${ALLOWED.join(', ')}; got \"${raw}\"`);\n}","typeGuard":"function isObservationQueueEngine(v: string): v is 'sqlite' | 'bullmq' {\n  return v === 'sqlite' || v === 'bullmq';\n}","tryCatchPattern":"try {\n  startQueue();\n} catch (err) {\n  if (err instanceof Error && err.message.includes('CLAUDE_MEM_QUEUE_ENGINE')) {\n    console.error('Fix CLAUDE_MEM_QUEUE_ENGINE in your env: use sqlite or bullmq', err.message);\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Keep allowed values in one shared constant and validate env at startup with a schema library (zod, envalid)","Never quote values inside .env files unless your loader strips quotes","Document the exact accepted strings next to the variable in your deploy templates","Fail fast: run env validation as the first step of your app, not at first queue use"],"tags":["configuration","environment","validation"],"backgroundTag":"invalid-env-var-value","analyzedSha":"d8bc9755e74915e5c3b999181e10a67c889bce2a","analyzedAt":"2026-09-17T16:40:26.182Z","contentChangedAt":"2026-09-17T16:40:26.182Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}