thedotmack/claude-mem · error

CLAUDE_MEM_QUEUE_ENGINE is not "bullmq"

Error message

CLAUDE_MEM_QUEUE_ENGINE is not "bullmq"

What it means

Thrown by collectBullmqCounts() in the server-jobs command when getRedisQueueConfig().engine is any value other than 'bullmq'. The function constructs live BullMQ Queue objects against the configured Redis connection, which is only valid under the bullmq engine; calling it under the in-memory engine would produce misleading counts or connection errors. It is a hard precondition guard before touching BullMQ APIs.

Source

Thrown at src/npx-cli/commands/server-jobs.ts:511

}> {
  if (testSeams.openPool) return testSeams.openPool();
  const { getSharedPostgresPool } = await import('../../storage/postgres/index.js');
  const pool = getSharedPostgresPool({ requireDatabaseUrl: true });
  return {
    pool: pool as never,
    releasePool: async () => { /* shared pool tears down on process exit */ },
  };
}

// BullMQ access. Direct construction avoids importing the runtime, keeping
// the CLI fast to boot. Returns counts per known queue name; gracefully
// returns null when Redis is unconfigured.
async function collectBullmqCounts(): Promise<Record<string, { waiting: number; active: number; completed: number; failed: number; delayed: number; stalled: number }>> {
  const { getRedisQueueConfig } = await import('../../server/queue/redis-config.js');
  const { Queue } = await import('bullmq');
  const config = getRedisQueueConfig();
  if (config.engine !== 'bullmq') {
    throw new Error('CLAUDE_MEM_QUEUE_ENGINE is not "bullmq"');
  }
  const { SERVER_JOB_QUEUE_NAMES } = await import('../../server/jobs/types.js');
  const out: Record<string, { waiting: number; active: number; completed: number; failed: number; delayed: number; stalled: number }> = {};
  for (const [kind, name] of Object.entries(SERVER_JOB_QUEUE_NAMES)) {
    const queue = new Queue(name, { connection: config.connection, prefix: config.prefix });
    try {
      const counts = await queue.getJobCounts('waiting', 'active', 'completed', 'failed', 'delayed');
      out[kind] = {
        waiting: Number(counts.waiting ?? 0),
        active: Number(counts.active ?? 0),
        completed: Number(counts.completed ?? 0),
        failed: Number(counts.failed ?? 0),
        delayed: Number(counts.delayed ?? 0),
        stalled: 0, // BullMQ rotates the stalled list; runtime tracks it via QueueEvents.
      };
    } finally {
      await queue.close();
    }

View on GitHub (pinned to d768ba3643)

Solutions

1. Set CLAUDE_MEM_QUEUE_ENGINE=bullmq and provide a reachable REDIS_URL, then retry.
2. If you did not intend to use BullMQ, do not invoke the BullMQ-specific counts path — use the memory-engine equivalent or omit the call.
3. Verify Redis is reachable and getRedisQueueConfig() returns engine='bullmq' before calling collectBullmqCounts().

Example fix

// before — calling BullMQ counts unconditionally
const counts = await collectBullmqCounts()
// after — guard on the engine first
const config = getRedisQueueConfig()
const counts = config.engine === 'bullmq' ? await collectBullmqCounts() : {}

const config = getRedisQueueConfig();
if (config.engine !== 'bullmq') return {}; // not a BullMQ deployment
const counts = await collectBullmqCounts();

function isBullmqEngine(config: { engine: string }): boolean {
  return config.engine === 'bullmq';
}

try {
  return await collectBullmqCounts();
} catch (e) {
  if (e instanceof Error && e.message.includes('not "bullmq"')) return {}; // memory engine
  throw e;
}

When it happens

Trigger: Running `claude-mem server-jobs` (or any caller of collectBullmqCounts) when CLAUDE_MEM_QUEUE_ENGINE is unset (defaulting to memory), set to 'memory', or set to any non-bullmq value. Also when Redis config resolution falls back because REDIS_URL is absent.

Common situations: Local dev without Redis, where the queue engine defaults to in-memory. A deployment that intentionally uses the memory engine but the CLI command assumes BullMQ. An env where REDIS_URL was expected but not exported, so getRedisQueueConfig returns a non-bullmq config.

Related errors

• Invalid CLAUDE_MEM_QUEUE_ENGINE=${raw}; expected sqlite or b
• Invalid CLAUDE_MEM_REDIS_MODE=${value}; expected external, m
• Invalid CLAUDE_MEM_REDIS_PORT=${value}; expected a TCP port
• CLAUDE_MEM_REDIS_URL must use redis:// or rediss://
• Invalid Redis database in CLAUDE_MEM_REDIS_URL: ${parsed.pat

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