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 by parse_url (connection.py:2352-2355) when a recognized query-string parameter fails its typed parser. URL_QUERY_ARGUMENT_PARSERS (lines 2310-2327) maps param names to converters (int, float, to_bool, parse_ssl_verify_flags, list); any TypeError or ValueError from the converter is caught and re-raised with this generic message naming the offending parameter.

Source

Thrown at redis/connection.py:2355

            "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 da03cdc7e8)

Solutions

1. Read the {name} in the error message to identify the offending parameter, then correct its value to the expected type (int/float/bool).
2. For numeric params (db, socket_timeout, protocol, max_connections, health_check_interval, socket_read_size, ssl_min_version, timeout) use plain numeric strings.
3. Substitute all template placeholders in the URL before passing it; log the final URL (redacting credentials) to confirm.
4. Validate critical values in your config loader before building the URL.

Example fix

# before
url = "redis://h:6379?protocol=three&db=zero"
redis.Redis.from_url(url)  # Invalid value for 'protocol'

# after
url = "redis://h:6379?protocol=3&db=0"
redis.Redis.from_url(url)

from urllib.parse import urlparse, parse_qs
TYPED = {"db","socket_timeout","socket_connect_timeout","socket_read_size",
         "max_connections","health_check_interval","ssl_min_version",
         "protocol","timeout"}
def validate_url_values(url: str):
    q = parse_qs(urlparse(url).query)
    for k, vals in q.items():
        if k in TYPED and vals:
            try:
                int(vals[0]) if k in {"db","socket_read_size","max_connections",
                 "health_check_interval","ssl_min_version","protocol"} else float(vals[0])
            except ValueError:
                raise ValueError(f"Query param {k}={vals[0]!r} is not numeric")
    return url

def url_query_value_is_valid(name: str, value: str) -> bool:
    numeric = {"db","socket_read_size","max_connections","health_check_interval","ssl_min_version","protocol"}
    floats = {"socket_timeout","socket_connect_timeout","timeout"}
    try:
        if name in numeric: int(value)
        elif name in floats: float(value)
    except ValueError:
        return False
    return True

try:
    client = redis.Redis.from_url(url)
except ValueError as e:
    if "Invalid value for" in str(e):
        # name is in the message; re-derive URL with corrected value
        client = redis.Redis.from_url(fixed_url)
    else:
        raise

When it happens

Trigger: A rediss:// or redis:// URL whose query string has a malformed value for a typed param, e.g. ?db=abc (int fails), ?socket_timeout=fast (float fails), ?protocol=three (int fails), ?max_connections=many, ?ssl_min_version=x. The {name} in the message identifies which parameter.

Common situations: Config typos in templated URLs or env vars; passing booleans as non-canonical strings that to_bool still accepts (those won't raise) but numeric fields with text will; URL-encoding issues where a placeholder wasn't substituted (e.g. ?db=${DB} left literal).

Related errors

• Redis URL must specify one of the following schemes (redis:/
• Invalid SSL Certificate Requirements Flag: {ssl_cert_reqs}
• Invalid ssl verify flag: {flag}
• Maintenance notifications are not supported with {connection
• 'username' and 'password' cannot be passed along with 'crede

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