redis/redis-py · error · ValueError

Invalid ssl verify flag: {flag}

Error message

Invalid ssl verify flag: {flag}

What it means

Raised as a ValueError from parse_ssl_verify_flags() when a comma-separated verify-flag string contains a name that is not an attribute of ssl.VerifyFlags (e.g. 'VERIFY_X509_STRICT'). This parser is invoked for the ssl_include_verify_flags / ssl_exclude_verify_flags URL query params, which are passed as a stringified list.

Source

Thrown at redis/asyncio/connection.py:1732

def to_bool(value) -> Optional[bool]:
    if value is None or value == "":
        return None
    if isinstance(value, str) and value.upper() in FALSE_STRINGS:
        return False
    return bool(value)


def parse_ssl_verify_flags(value):
    # flags are passed in as a string representation of a list,
    # e.g. VERIFY_X509_STRICT, VERIFY_X509_PARTIAL_CHAIN
    verify_flags_str = value.replace("[", "").replace("]", "")

    verify_flags = []
    for flag in verify_flags_str.split(","):
        flag = flag.strip()
        if not hasattr(VerifyFlags, flag):
            raise ValueError(f"Invalid ssl verify flag: {flag}")
        verify_flags.append(getattr(VerifyFlags, flag))
    return verify_flags


URL_QUERY_ARGUMENT_PARSERS: Mapping[str, Callable[..., object]] = MappingProxyType(
    {
        "db": int,
        "socket_timeout": float,
        "socket_connect_timeout": float,
        "socket_read_size": int,
        "socket_keepalive": to_bool,
        "retry_on_timeout": to_bool,
        "max_connections": int,
        "health_check_interval": int,
        "ssl_check_hostname": to_bool,
        "ssl_include_verify_flags": parse_ssl_verify_flags,
        "ssl_exclude_verify_flags": parse_ssl_verify_flags,
        "ssl_min_version": int,

View on GitHub (pinned to da03cdc7e8)

Solutions

  1. Confirm the flag exists on your Python: 'ssl.VerifyFlags.__members__'.
  2. Use the exact uppercase constant name (e.g. VERIFY_X509_STRICT).
  3. Pass ssl.VerifyFlags constants directly via the Redis(...) kwargs instead of the URL string form.
  4. Upgrade Python/OpenSSL if the flag is genuinely missing.

Example fix

// before
r = redis.asyncio.from_url("rediss://host?ssl_include_verify_flags=VERIFY_X509_STRICT,FOO")

// after
import ssl
r = redis.asyncio.Redis(host=h, port=p, ssl=True, ssl_include_verify_flags=[ssl.VerifyFlags.VERIFY_X509_STRICT])
Defensive patterns

Strategy: validation

Validate before calling

import ssl
def validate_verify_flag_names(names: list[str]) -> list[str]:
    valid = set(ssl.VerifyFlags.__members__)
    bad = [n for n in names if n not in valid]
    if bad:
        raise ValueError(f"Unknown VerifyFlags: {bad}; valid={sorted(valid)}")
    return names

Type guard

def is_known_verify_flag(name: str) -> bool:
    import ssl
    return hasattr(ssl.VerifyFlags, name)

Try / catch

try:
    r = redis.asyncio.from_url(url)
except ValueError as e:
    if "Invalid ssl verify flag" in str(e):
        # remove the offending query param or pass constants directly
        r = redis.asyncio.Redis(host=h, port=p, ssl=True)
    else:
        raise

Prevention

When it happens

Trigger: Using rediss://host?ssl_include_verify_flags=FOO or ?ssl_exclude_verify_flags=VERIFY_X509_TRUSTED_LAST where FOO/that-name is not a member of ssl.VerifyFlags on the running Python. The function strips brackets, splits on commas, and checks hasattr(VerifyFlags, flag).

Common situations: Typing a flag name wrong (VERIFY_X509_STRICT vs VERIFY_X509_STRICT-ish); flags that exist only on newer Python/OpenSSL (e.g. VERIFY_X509_PARTIAL_CHAIN on older builds); passing the ssl constant's int value as a string instead of its name; case mismatch (names are uppercase).

Related errors

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