What causes "Invalid unix URL" in redis/node-redis?

Provide the full socket file path, e.g. unix:///var/run/redis/redis.sock.

redis/node-redis · error · TypeError

Invalid unix URL

Error message

Invalid unix URL

What it means

RedisClient.#parseUnixURL expects unix://[user[:password]@]/path/to/sock[?db=N]. The regex must match AND the path group (match[3]) must not be just '/'. An empty socket path or a URL shaped like unix://host/path (the regex forbids a bare host before the path) is rejected.

Solutions

Provide the full socket file path, e.g. unix:///var/run/redis/redis.sock.
If you need credentials, place them before the path: unix://user:pass@/var/run/redis/redis.sock.

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

function assertUnixUrl(url) {
  const m = /^unix:\/\/(?:([^:@/]*)(?::([^@/]*))?@)?(\/[^?#]*)(?:\?([^#]*))?(?:#.*)?$/.exec(url);
  if (!m || m[3] === '/') {
    throw new TypeError(`Invalid unix URL ${url}; expected unix://[user[:pass]@]/path/to/sock[?db=N]`);
  }
}

Prevention

Always include the full socket file path in a unix:// URL.
Do not URL-encode the leading slash of the socket path.
Test socket URLs in isolation before wiring them into config.

When it happens

Trigger: Passing 'unix://' with no path, 'unix:///' (bare slash), or a URL whose authority section breaks the expected shape.

Common situations: Forgetting to include the socket file path; treating a unix:// URL like a tcp URL with a host; URL-encoding the path so the regex no longer matches.

Related errors

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

Appendix: 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 90fd0652bc)