redis/redis-py · error · ValueError

Invalid value for '{name}' in connection URL.

Error message

Invalid value for '{name}' in connection URL.

What it means

Raised as a ValueError from parse_url() when a recognized URL query parameter (db, socket_timeout, socket_connect_timeout, protocol, health_check_interval, etc.) fails its typed parser (int/float/to_bool/parse_ssl_verify_flags) with TypeError or ValueError. The name of the offending query key is reported. Unknown keys are passed through as strings and do not trigger this.

Source

Thrown at redis/asyncio/connection.py:1783

    path: str


def parse_url(url: str) -> ConnectKwargs:
    parsed: ParseResult = urlparse(url)
    kwargs: ConnectKwargs = {}

    for name, value_list in parse_qs(parsed.query).items():
        if value_list and len(value_list) > 0:
            # parse_qs() already percent-decodes query values, so use the value
            # as-is; unquoting again here would double-decode (e.g. "%2520" ->
            # "%20" -> " "). See issue #4208.
            value = value_list[0]
            parser = URL_QUERY_ARGUMENT_PARSERS.get(name)
            if parser:
                try:
                    kwargs[name] = parser(value)
                except (TypeError, ValueError):
                    raise ValueError(f"Invalid value for '{name}' in connection URL.")
            else:
                kwargs[name] = value

    if parsed.username:
        kwargs["username"] = unquote(parsed.username)
    if parsed.password:
        kwargs["password"] = unquote(parsed.password)

    # We only support redis://, rediss:// and unix:// schemes.
    if parsed.scheme == "unix":
        if parsed.path:
            kwargs["path"] = unquote(parsed.path)
        kwargs["connection_class"] = UnixDomainSocketConnection

    elif parsed.scheme in ("redis", "rediss"):
        if parsed.hostname:
            kwargs["host"] = unquote(parsed.hostname)
        if parsed.port:

View on GitHub (pinned to da03cdc7e8)

Solutions

  1. Inspect the named query param in the URL and correct its value to the expected type (int/float/bool).
  2. For booleans use 0/1 or true/false (handled by to_bool).
  3. Remove the param to fall back to the library default rather than passing garbage.
  4. Validate the URL with urllib.parse_qs before passing it to from_url.

Example fix

// before
r = redis.asyncio.from_url("redis://host:6379?socket_timeout=fast&protocol=three")

// after
r = redis.asyncio.from_url("redis://host:6379?socket_timeout=1.5&protocol=3")
Defensive patterns

Strategy: validation

Validate before calling

from urllib.parse import urlparse, parse_qs
TYPED_PARAMS = {"db": int, "socket_timeout": float, "socket_connect_timeout": float,
    "socket_read_size": int, "max_connections": int, "health_check_interval": int,
    "ssl_min_version": int, "protocol": int, "timeout": float}
def validate_redis_url(url: str) -> None:
    for k, vs in parse_qs(urlparse(url).query).items():
        if k in TYPED_PARAMS:
            TYPED_PARAMS[k](vs[0])  # raises on bad value

Try / catch

try:
    r = redis.asyncio.from_url(url)
except ValueError as e:
    if "Invalid value for" in str(e):
        # strip typed query params and pass them as kwargs instead
        r = redis.asyncio.from_url(base_url, socket_timeout=1.5)
    else:
        raise

Prevention

When it happens

Trigger: A redis:// or rediss:// URL with a query param that has a typed parser but a malformed value: ?db=abc (int parse fails), ?socket_timeout=fast (float fails), ?protocol=three (int fails), ?ssl_min_version= (int fails), ?health_check_interval=-x.

Common situations: Typos in query values; copy-paste from docs with placeholders left in; environment-variable interpolation that left an empty or non-numeric value; passing 'true'/'false' to a non-bool param like db or protocol.

Related errors

AI-assisted analysis of redis/redis-py@da03cdc7e8 (2026-08-04). Data as JSON: /data/errors/7fb9ecf297444df5.json. Report an issue: GitHub.