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

Use an integer for db: unix:///path/to/sock?db=2, or omit it (defaults to 0).

redis/node-redis · error · TypeError

Invalid db query parameter

Error message

Invalid db query parameter

What it means

Inside #parseUnixURL, the optional query string may carry a `db` parameter (e.g. unix:///path/to/sock?db=2). If db is present but not a valid number (Number(db) is NaN), the client throws 'Invalid db query parameter'. This is the unix-socket analog of the 'Invalid pathname' check for tcp URLs.

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 bb5beb5657)

Solutions

Use an integer for db: unix:///path/to/sock?db=2, or omit it (defaults to 0).
Prefer the `database` option on createClient for clarity instead of the query string.
Validate the db value at config-load time.

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

function redisDbFromUnixUrl(url) {
  const q = new URL(url.startsWith('unix://') ? 'http://x' + url.slice('unix'.length) : url).searchParams;
  const db = q.get('db');
  if (db !== null && (!Number.isInteger(Number(db)) || Number(db) < 0)) {
    throw new TypeError('Invalid db query parameter');
  }
}

Prevention

Use an integer for the db query param, or omit it.
Prefer the `database` createClient option for clarity.

When it happens

Trigger: `unix:///path/to/sock?db=abc`; `?db=primary`; a query string with a non-numeric db; copy-pasting a query string that includes other params and a malformed db.

Common situations: Passing a logical DB name in the query; typo in the db value; a service template that injects a non-numeric db.

Related errors

AI-assisted analysis of redis/node-redis@bb5beb5657 (2026-08-03). Data as JSON: /data/errors/d6e66868ab19c347.json. Report an issue: GitHub.