What causes "Invalid db query parameter" in redis/node-redis?

Drop the ?db= parameter entirely, or

redis/node-redis · error · TypeError

Invalid db query parameter

Error message

Invalid db query parameter

What it means

For unix:// URLs the optional ?db=N query parameter selects the logical database and must be numeric. A non-numeric db value (e.g. ?db=foo) is rejected by Number()/isNaN validation.

Solutions

Drop the ?db= parameter entirely, or
Use an integer db index (0..15 typically).

Example fix

// before
createClient({ url: 'unix:///var/run/redis/redis.sock?db=main' });

// after
createClient({ url: 'unix:///var/run/redis/redis.sock?db=0' });

Defensive patterns

Strategy: validation

Validate before calling

function assertUnixDb(url) {
  const q = new URL(url, 'unix://x/').searchParams; // parse query loosely
  const db = q.get('db');
  if (db != null && !/^\d+$/.test(db)) {
    throw new TypeError(`Invalid db query parameter ${db}; expected integer`);
  }
}

Prevention

Only use integer db indexes in the ?db= query parameter.
Omit ?db= to default to db 0.
Validate the query string at config load.

When it happens

Trigger: Passing unix:///var/run/redis/redis.sock?db=primary or any non-integer db.

Common situations: Trying to encode cluster/sentinel hints in the db slot; typo; confusing the db index with a name.

Related errors

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

Appendix: source

Thrown at packages/client/lib/client/index.ts:580

    }

    if (username || password) {
      parsed.credentialsProvider = {
        type: 'async-credentials-provider',
        credentials: async () => (
          {
            username: username ? decodeURIComponent(username) : undefined,
            password: password ? decodeURIComponent(password) : undefined
          })
      };
    }

    if (rawQuery) {
      const db = new URLSearchParams(rawQuery).get('db');
      if (db !== null) {
        const database = Number(db);
        if (isNaN(database)) {
          throw new TypeError('Invalid db query parameter');
        }
        parsed.database = database;
      }
    }

    return parsed;
  }

  readonly #options: RedisClientOptions<M, F, S, RESP, TYPE_MAPPING>;
  #socket: RedisSocket;
  readonly #queue: RedisCommandsQueue;
  #selectedDB = 0;
  #monitorCallback?: MonitorCallback<TYPE_MAPPING>;
  private _self = this;
  private _commandOptions?: CommandOptions<TYPE_MAPPING>;
  // flag used to annotate that the client
  // was in a watch transaction when
  // a topology change occurred

View on GitHub (pinned to 90fd0652bc)