redis/node-redis · error · TypeError

Invalid unix URL

Error message

Invalid unix URL

What it means

For unix:// URLs the client uses a regex (#parseUnixURL) because WHATWG URL cannot parse a unix authority. The regex requires a non-root socket path (the part after unix://[user[:pass]@]); if the match fails or the path is exactly '/', it throws 'Invalid unix URL'. A unix socket URL must therefore be of the form unix:///var/run/redis/redis-server.sock (optionally with credentials and a ?db=N query).

Source

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

      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');
    }

    const [, username, password, rawPath, rawQuery] = match,
      parsed: AnyRedisClientOptions & {
        socket: Exclude<AnyRedisClientOptions['socket'], undefined> & {
          tls: boolean
        }
      } = {
        socket: {
          path: decodeURIComponent(rawPath),
          tls: false
        }
      };

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

View on GitHub (pinned to bb5beb5657)

Solutions

1. Provide the full socket path: 'unix:///var/run/redis/redis-server.sock'.
2. If you meant a TCP connection, use 'redis://host:port' instead of 'unix://'.
3. Include credentials as unix://user:pass@/path/to/sock if needed.

Example fix

// before
createClient({ url: 'unix://localhost:6379' });

// after
createClient({ socket: { host: 'localhost', port: 6379 } });
// or for an actual unix socket:
createClient({ url: 'unix:///var/run/redis/redis-server.sock' });

function assertUnixUrl(url) {
  if (!/^unix:\/\/(?:[^:@\/]*(?::[^@\/]*)?@)?\/[^?#]+/.test(url)) {
    throw new TypeError('Expected unix:///path/to/sock');
  }
}

When it happens

Trigger: `createClient({ url: 'unix://' })` (no path); `unix://localhost:6379` (treating it like a tcp URL); a malformed path missing the leading slash; a unix URL with credentials in an unsupported position.

Common situations: Confusing unix:// with redis:// (passing host:port to unix://); typo in the socket path; copy-pasting a Redis URI but keeping the unix:// scheme; building the URL dynamically and dropping the path component.

Related errors

• Invalid db query parameter
• tls socket option is set to ${options.socket.tls} which is m
• Invalid protocol
• Invalid pathname
• expirationRefreshRatio must be less than or equal to 1

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