Invalid CLAUDE_MEM_QUEUE_ENGINE=${raw}; expected sqlite or b

Error message

Invalid CLAUDE_MEM_QUEUE_ENGINE=${raw}; expected sqlite or bullmq

What it means

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.

Source

Thrown at src/server/queue/redis-config.ts:27

export type ObservationQueueEngineName = 'sqlite' | 'bullmq';
export type RedisMode = 'external' | 'managed' | 'docker';

export interface RedisQueueConfig {
  engine: ObservationQueueEngineName;
  mode: RedisMode;
  url: string | null;
  host: string;
  port: number;
  prefix: string;
  connection: RedisOptions;
}

export function getObservationQueueEngineName(): ObservationQueueEngineName {
  const raw = getQueueSetting('CLAUDE_MEM_QUEUE_ENGINE').trim().toLowerCase();
  if (raw === 'sqlite' || raw === 'bullmq') {
    return raw;
  }
  throw new Error(`Invalid CLAUDE_MEM_QUEUE_ENGINE=${raw}; expected sqlite or bullmq`);
}

export function getRedisQueueConfig(): RedisQueueConfig {
  const engine = getObservationQueueEngineName();
  const mode = normalizeRedisMode(getQueueSetting('CLAUDE_MEM_REDIS_MODE'));
  const url = getQueueSetting('CLAUDE_MEM_REDIS_URL').trim() || null;
  const host = getQueueSetting('CLAUDE_MEM_REDIS_HOST').trim() || '127.0.0.1';
  const port = parseRedisPort(getQueueSetting('CLAUDE_MEM_REDIS_PORT'));
  const prefix = sanitizePrefix(getQueueSetting('CLAUDE_MEM_QUEUE_REDIS_PREFIX'));
  const connection = url ? connectionFromUrl(url) : connectionFromHost(host, port);

  return {
    engine,
    mode,
    url,
    host: url ? describeUrlHost(url).host : host,
    port: url ? describeUrlHost(url).port : port,
    prefix,

View on GitHub (pinned to d768ba3643)

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.

Example fix

// before: export CLAUDE_MEM_QUEUE_ENGINE=redis
// after (server): export CLAUDE_MEM_QUEUE_ENGINE=bullmq
// after (local): export CLAUDE_MEM_QUEUE_ENGINE=sqlite

Defensive patterns

Strategy: validation

Validate before calling

function resolveQueueEngine(): 'sqlite' | 'bullmq' {
  const raw = (process.env.CLAUDE_MEM_QUEUE_ENGINE ?? '').trim().toLowerCase();
  if (raw !== 'sqlite' && raw !== 'bullmq') {
    throw new Error('Set CLAUDE_MEM_QUEUE_ENGINE to sqlite or bullmq');
  }
  return raw;
}

Type guard

function isQueueEngineName(v: string): v is 'sqlite' | 'bullmq' {
  return v === 'sqlite' || v === 'bullmq';
}

Try / catch

try {
  engine = getObservationQueueEngineName();
} catch (error) {
  // print guidance and exit; do not default silently
  console.error((error as Error).message);
  process.exit(1);
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of thedotmack/claude-mem@d768ba3643 (2026-08-12). Data as JSON: /api/errors/617c76e37399c96b. Report an issue: GitHub.