redis/node-redis · error · TypeError

Invalid protocol

Error message

Invalid protocol

What it means

parseURL uses the WHATWG URL parser to read a redis/rediss URI; if the scheme is neither 'redis:' nor 'rediss:' it throws 'Invalid protocol'. Only those two IANA-registered schemes map to a Redis socket; anything else (http:, postgres://, mongodb://, typo like 'redi://') is rejected at parse time.

Source

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

      return RedisClient.#parseUnixURL(url);
    }

    // https://www.iana.org/assignments/uri-schemes/prov/redis
    const { hostname, port, protocol, username, password, pathname } = new URL(url),
      parsed: AnyRedisClientOptions & {
        socket: Exclude<AnyRedisClientOptions['socket'], undefined> & {
          tls: boolean
        }
      } = {
        socket: {
          // Use net.SocketAddress.parse() once supported.
          host: hostname.replace(/^\[([0-9a-f:]+)\]$/, '$1'),
          tls: false
        }
      };

    if (protocol !== 'redis:' && protocol !== 'rediss:') {
      throw new TypeError('Invalid protocol');
    }

    parsed.socket.tls = protocol === 'rediss:';

    if (port) {
      (parsed.socket as TcpSocketConnectOpts).port = Number(port);
    }

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

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

    if (username || password) {
      parsed.credentialsProvider = {

View on GitHub (pinned to bb5beb5657)

Solutions

1. Use a URL beginning with 'redis://' (plain) or 'rediss://' (TLS).
2. Double-check the env var name and value; strip whitespace.
3. If your service discovery returns a custom scheme, map it to redis:// or rediss:// before passing to createClient.

Example fix

// before
createClient({ url: process.env.DATABASE_URL }); // 'postgres://...'

// after
createClient({ url: process.env.REDIS_URL }); // 'redis://...'

function assertRedisUrl(url) {
  if (!/^rediss?:\/\//.test(url.trim())) {
    throw new TypeError(`Expected redis:// or rediss:// URL, got ${url}`);
  }
}

When it happens

Trigger: `createClient({ url: 'http://host:6379' })`; a typo'd scheme ('redi://', 'redsi://'); passing a non-Redis connection string that happens to live in the same config; an env var containing a generic database URL.

Common situations: Wrong env var wired to the Redis client; copy-paste from another service's connection string; a leading/trailing space or stray character breaking the scheme; a service-discovery URL using a custom scheme.

Related errors

• tls socket option is set to ${options.socket.tls} which is m
• Invalid pathname
• Invalid unix URL
• Invalid db query parameter
• 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/b10338da0f5476a3.json. Report an issue: GitHub.