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 from parse_url() when a registered URL query parameter fails to coerce via its parser (int/float/to_bool/parse_ssl_verify_flags). The message reports the offending parameter name. parse_qs already percent-decodes values, so the parser sees the raw token; if int('abc') or to_bool(bad) raises TypeError/ValueError, the URL is rejected.

Solutions

  1. Use numeric values for db/protocol/max_connections/socket_read_size/health_check_interval.
  2. For booleans use true/false (or one of 0/F/FALSE/N/NO for false; anything else is truthy).
  3. Validate/normalize the URL at config-load time before passing to from_url.
  4. For verify flags, pass ssl.VerifyFlags constants directly instead of a URL string.

Example fix

// before
r = redis.asyncio.from_url('redis://host?db=two&ssl_check_hostname=yes')
// after
r = redis.asyncio.from_url('redis://host?db=2&ssl_check_hostname=true')
Defensive patterns

Strategy: validation

Validate before calling

from urllib.parse import parse_qs

def validate_query_params(url: str) -> dict:
    numeric = {'db', 'socket_timeout', 'socket_connect_timeout', 'socket_read_size',
               'max_connections', 'health_check_interval', 'ssl_min_version',
               'protocol', 'timeout'}
    boolish = {'socket_keepalive', 'retry_on_timeout', 'ssl_check_hostname', 'legacy_responses'}
    out = {}
    for k, vs in parse_qs(urlparse(url).query).items():
        v = vs[0]
        if k in numeric:
            out[k] = (int if k in {'db','socket_read_size','max_connections','health_check_interval','protocol','ssl_min_version'} else float)(v)
        elif k in boolish:
            out[k] = v.lower() not in ('0','f','false','n','no')
        else:
            out[k] = v
    return out

Type guard

def is_bad_query_value(exc: BaseException) -> bool:
    return isinstance(exc, ValueError) and 'connection URL' in str(exc)

Try / catch

try:
    r = redis.asyncio.from_url(url)
except ValueError as e:
    if 'connection URL' in str(e):
        # log and fall back to defaults
        r = redis.asyncio.Redis(host=h)
    else:
        raise

Prevention

When it happens

Trigger: Passing ?db=abc, ?socket_timeout=fast, ?protocol=3.5, ?ssl_check_hostname=yes, ?max_connections=many, or an unparsable verify-flags list. Any non-numeric db/timeout/protocol or non-bool boolean triggers it.

Common situations: Typo in a numeric query param; passing 'yes'/'no'/'on'/'off' (only a limited FALSE_STRINGS set is honored: 0/F/FALSE/N/NO); negative or fractional values where int is required (db, protocol); URL-encoding mishandling.

Related errors

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

Appendix: source

Thrown at redis/asyncio/connection.py:1792

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

    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

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

View on GitHub (pinned to 6a6b581b48)