redis/redis-py · error · ValueError

Invalid value for ' ' in connection URL.

Error message

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

What it means

Raised as ValueError(f"Invalid value for '{name}' in connection URL.") by parse_url when a query-string parameter registered in URL_QUERY_ARGUMENT_PARSERS cannot be coerced by its typed parser. The per-name parsers (int for db/max_connections/health_check_interval/protocol/ssl_min_version, float for socket_timeout/socket_connect_timeout/timeout, to_bool, list, parse_ssl_verify_flags) raise TypeError or ValueError on bad input, which parse_url re-wraps into this message.

Solutions

  1. Check the offending query param and give it a value of the right type (db=0, socket_timeout=2.5, protocol=3, etc.).
  2. For ssl_min_version pass the integer value of ssl.TLSVersion (e.g. ssl.TLSVersion.TLSv1_3.value).
  3. Validate/escape templated URLs before they reach from_url.

Example fix

# before
r = redis.Redis.from_url('redis://host?socket_timeout=fast&db=two')
# after
r = redis.Redis.from_url('redis://host?socket_timeout=2.5&db=2')
Defensive patterns

Strategy: try-catch

Validate before calling

from redis.connection import URL_QUERY_ARGUMENT_PARSERS

def validate_query_values(url: str) -> None:
    from urllib.parse import urlparse, parse_qs
    parsed = parse_qs(urlparse(url).query)
    for name, vals in parsed.items():
        parser = URL_QUERY_ARGUMENT_PARSERS.get(name)
        if parser and vals:
            try:
                parser(vals[0])
            except (TypeError, ValueError):
                raise ValueError(f'Query param {name!r}={vals[0]!r} is invalid for parser {parser.__name__}')

Try / catch

try:
    r = redis.Redis.from_url(url)
except ValueError as e:
    if 'Invalid value for' in str(e):
        # log the bad param and fall back to a known-good URL without query params
        r = redis.Redis.from_url(strip_query_params(url))
    else:
        raise

Prevention

When it happens

Trigger: A URL like redis://host?db=abc (int parse fails), ?socket_timeout=fast (float parse fails), ?max_connections=many, ?protocol=three, or ?ssl_min_version=foo. Any query key in URL_QUERY_ARGUMENT_PARSERS whose value does not match its parser.

Common situations: Typing numeric query params as words. Passing an enum name where an int is expected (ssl_min_version expects the integer TLS version). Misconfigured env vars or templated URLs that interpolate non-numeric values.

Related errors

AI-assisted analysis of redis/redis-py@6a6b581b48 (2026-08-10). Data as JSON: /api/errors/f07ca63348e9d2e4. Report an issue: GitHub.

Appendix: source

Thrown at redis/connection.py:2370

            "Redis URL must specify one of the following "
            "schemes (redis://, rediss://, unix://)"
        )

    url = urlparse(url)
    kwargs = {}

    for name, value in parse_qs(url.query).items():
        if value and len(value) > 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[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 url.username:
        kwargs["username"] = unquote(url.username)
    if url.password:
        kwargs["password"] = unquote(url.password)

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

    else:  # implied:  url.scheme in ("redis", "rediss"):
        if url.hostname:
            kwargs["host"] = unquote(url.hostname)
        if url.port:

View on GitHub (pinned to 6a6b581b48)