thedotmack/claude-mem · error

CLAUDE_MEM_REDIS_URL must use redis:// or rediss://

Error message

CLAUDE_MEM_REDIS_URL must use redis:// or rediss://

What it means

Thrown by connectionFromUrl() when CLAUDE_MEM_REDIS_URL's URL protocol is neither 'redis:' nor 'rediss:'. The URL is parsed with the standard URL parser, so a malformed URL will instead throw a TypeError from `new URL()` before this check; this specific error is for a well-formed URL with the wrong scheme (e.g. http://, postgres://).

Source

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

function sanitizePrefix(value: string): string {
  return (value.trim() || 'claude_mem').replace(/[^a-zA-Z0-9_-]/g, '_');
}

function connectionFromHost(host: string, port: number): RedisOptions {
  return {
    host,
    port,
    maxRetriesPerRequest: null,
    connectTimeout: 1000,
    lazyConnect: true,
  };
}

function connectionFromUrl(rawUrl: string): RedisOptions {
  const parsed = new URL(rawUrl);
  if (parsed.protocol !== 'redis:' && parsed.protocol !== 'rediss:') {
    throw new Error('CLAUDE_MEM_REDIS_URL must use redis:// or rediss://');
  }
  const db = parsed.pathname.length > 1
    ? Number.parseInt(parsed.pathname.slice(1), 10)
    : undefined;
  if (db !== undefined && (!Number.isInteger(db) || db < 0)) {
    throw new Error(`Invalid Redis database in CLAUDE_MEM_REDIS_URL: ${parsed.pathname}`);
  }
  return {
    host: parsed.hostname || '127.0.0.1',
    port: parsed.port ? Number.parseInt(parsed.port, 10) : 6379,
    username: parsed.username ? decodeURIComponent(parsed.username) : undefined,
    password: parsed.password ? decodeURIComponent(parsed.password) : undefined,
    db,
    tls: parsed.protocol === 'rediss:' ? {} : undefined,
    maxRetriesPerRequest: null,
    connectTimeout: 1000,
    lazyConnect: true,
  };

View on GitHub (pinned to d768ba3643)

Solutions

1. Use the redis:// scheme (or rediss:// for TLS-encrypted Redis).
2. For TLS, ensure the full URL is rediss://host:port and the Redis server presents a valid cert.
3. Double-check the string is the Redis connection URL and not another service's.

Example fix

// before: export CLAUDE_MEM_REDIS_URL=https://redis.example.com:6379
// after (TLS): export CLAUDE_MEM_REDIS_URL=rediss://redis.example.com:6379
// after (plain): export CLAUDE_MEM_REDIS_URL=redis://127.0.0.1:6379

function assertRedisUrlScheme(rawUrl: string): void {
  const parsed = new URL(rawUrl); // throws TypeError if malformed
  if (parsed.protocol !== 'redis:' && parsed.protocol !== 'rediss:') {
    throw new Error('CLAUDE_MEM_REDIS_URL must use redis:// or rediss://');
  }
}

function isRedisSchemeUrl(rawUrl: string): boolean {
  try {
    const p = new URL(rawUrl).protocol;
    return p === 'redis:' || p === 'rediss:';
  } catch {
    return false;
  }
}

try {
  conn = connectionFromUrl(rawUrl);
} catch (error) {
  if (/must use redis:\/\/ or rediss:\/\//.test((error as Error).message)) {
    console.error('Fix CLAUDE_MEM_REDIS_URL scheme to redis:// or rediss://');
    process.exit(1);
  }
  throw error;
}

When it happens

Trigger: CLAUDE_MEM_REDIS_URL is set with an http://, https://, or other non-Redis scheme; a copy-paste of a connection string from a different service.

Common situations: Operator pastes a Postgres/HTTP URL by mistake. A rediss:// URL was downgraded to https:// by a tool. A typo in the scheme.

Related errors

• Invalid Redis database in CLAUDE_MEM_REDIS_URL: ${parsed.pat
• CLAUDE_MEM_QUEUE_ENGINE is not "bullmq"
• Invalid CLAUDE_MEM_REDIS_MODE=${value}; expected external, m
• Invalid CLAUDE_MEM_REDIS_PORT=${value}; expected a TCP port
• server startup configuration is invalid: - ${line}

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