What causes "Invalid pathname" in redis/node-redis?

Use an integer database index in the path: redis://host:6379/3, or omit it (defaults to 0).

redis/node-redis · error · TypeError

Invalid pathname

Error message

Invalid pathname

What it means

In parseURL, if the URL pathname is longer than just '/', the client treats the segment after the slash as the database number (e.g. /3 => database 3). If Number(pathname) is NaN — e.g. '/abc' or '/1a' — it cannot SELECT a valid DB and throws 'Invalid pathname'. Only an integer DB index (or empty pathname) is accepted.

Source

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

    if (password) {
      parsed.password = decodeURIComponent(password);
    }

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

    if (pathname.length > 1) {
      const database = Number(pathname.substring(1));
      if (isNaN(database)) {
        throw new TypeError('Invalid pathname');
      }

      parsed.database = database;
    }

    return parsed;
  }

  static #parseUnixURL(url: string): AnyRedisClientOptions & {
    socket: Exclude<AnyRedisClientOptions['socket'], undefined> & {
      tls: boolean
    }
  } {
    // unix://[user[:password]@]/path/to/sock[?db=N]
    const match = /^unix:\/\/(?:([^:@/]*)(?::([^@/]*))?@)?(\/[^?#]*)(?:\?([^#]*))?(?:#.*)?$/.exec(url);
    if (!match || match[3] === '/') {
      throw new TypeError('Invalid unix URL');
    }

View on GitHub (pinned to bb5beb5657)

Solutions

Use an integer database index in the path: redis://host:6379/3, or omit it (defaults to 0).
If you need logical isolation, use the `keyPrefix` option or SELECT a DB via the `database` option instead of the path.
Move tenant/namespace info out of the URL path.

Example fix

// before
createClient({ url: 'redis://host:6379/tenantA' });

// after
createClient({ url: 'redis://host:6379/0', keyPrefix: 'tenantA:' });

Defensive patterns

Strategy: validation

Validate before calling

function redisDbFromUrl(url) {
  const u = new URL(url);
  if (u.pathname.length > 1) {
    const db = Number(u.pathname.slice(1));
    if (!Number.isInteger(db) || db < 0) throw new TypeError('Invalid DB in URL path');
    return db;
  }
  return 0;
}

Prevention

Put only an integer DB index in the URL path (or omit it).
Use keyPrefix or the database option for logical isolation instead of a path name.

When it happens

Trigger: `createClient({ url: 'redis://host:6379/abc' })`; `redis://host/mydb`; a URL with a trailing path component that is not an integer (e.g. a service path or tenant id mistakenly placed in the path).

Common situations: Putting a logical name/tenant in the URL path instead of a numeric DB; copy-paste from a multi-tenant URL scheme; a proxy that appends a path segment; confusion with HTTP-style path routing.

Related errors

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