redis/node-redis · error · Error

REDIS_ENDPOINTS_CONFIG_PATH must be set when RE_CLUSTER=true

Error message

REDIS_ENDPOINTS_CONFIG_PATH must be set when RE_CLUSTER=true

What it means

loadREConnection() throws when RE_CLUSTER=true is active but REDIS_ENDPOINTS_CONFIG_PATH is unset. That env var must point to a JSON file describing the Redis Enterprise databases — the same format the scenario tests consume. Without it, the loader cannot determine which managed database to target.

Source

Thrown at packages/test-utils/lib/re-cluster.ts:47

 * Docker servers.
 */
export function isReCluster(): boolean {
  return (process.env.RE_CLUSTER ?? '').toLowerCase() === 'true';
}

let cached: REConnection | undefined;

/**
 * Resolves the managed Redis Enterprise database the suite should target, reading
 * the database named by RE_DB_NAME (default "standalone") from the endpoints config
 * at REDIS_ENDPOINTS_CONFIG_PATH - the same format consumed by the scenario tests.
 */
export function loadREConnection(): REConnection {
  if (cached) return cached;

  const path = process.env.REDIS_ENDPOINTS_CONFIG_PATH;
  if (!path) {
    throw new Error('REDIS_ENDPOINTS_CONFIG_PATH must be set when RE_CLUSTER=true');
  }

  const data = JSON.parse(readFileSync(path, 'utf-8')) as REDatabasesConfig;
  const name = process.env.RE_DB_NAME || 'standalone';
  const db = data[name] ?? Object.values(data)[0];
  if (!db) {
    throw new Error(`Database ${name} not found in ${path}`);
  }

  let host: string;
  let port: number;
  if (db.raw_endpoints && db.raw_endpoints.length > 0) {
    host = db.raw_endpoints[0].dns_name;
    port = db.raw_endpoints[0].port;
  } else if (db.endpoints && db.endpoints.length > 0) {
    const parsed = new URL(db.endpoints[0]);
    host = parsed.hostname;
    port = parsed.port ? Number(parsed.port) : parsed.protocol === 'rediss:' ? 6380 : 6379;

View on GitHub (pinned to 90fd0652bc)

Solutions

1. Generate or mount the endpoints JSON and export an absolute path: export REDIS_ENDPOINTS_CONFIG_PATH=/abs/path/endpoints.json.
2. If you did not mean to use RE mode, unset RE_CLUSTER (or set RE_CLUSTER=false) to fall back to local Docker servers.
3. Confirm the path is readable by the test process and points at the file you expect (ls -l $REDIS_ENDPOINTS_CONFIG_PATH).
4. Check for trailing whitespace or a missing export when assigning the variable.

Example fix

# before
 export RE_CLUSTER=true                 # REDIS_ENDPOINTS_CONFIG_PATH unset -> throws

# after
 export RE_CLUSTER=true
 export REDIS_ENDPOINTS_CONFIG_PATH=/etc/redis/endpoints.json
 npm run test

function assertEndpointsConfigPath(): string {
  const path = process.env.REDIS_ENDPOINTS_CONFIG_PATH;
  if (!path) {
    throw new Error('Set REDIS_ENDPOINTS_CONFIG_PATH=<abs/path/endpoints.json> when RE_CLUSTER=true');
  }
  return path;
}

When it happens

Trigger: Setting RE_CLUSTER=true without also providing REDIS_ENDPOINTS_CONFIG_PATH; running the suite in RE mode before the cae-client-testing pipeline has generated/mounted the endpoints config.

Common situations: CI job mounted the config but forgot to set the env var; locally toggling RE_CLUSTER without the config file; env var renamed; the config-generation step ran in a different shell than the tests.

Related errors

• RE_FAULT_INJECTOR_URL environment variable must be set
• Database ${name} not found in ${path}
• No endpoints found for database ${name} in ${path}
• Invalid JSON configuration: ${error}
• Config file not found at path: ${path}

AI-assisted analysis of redis/node-redis@90fd0652bc (2026-08-11). Data as JSON: /api/errors/d9e5cbc882b5f8f6. Report an issue: GitHub.