redis/redis-py · error · ValueError

Invalid ssl verify flag

Error message

Invalid ssl verify flag: {flag}

What it means

Raised as ValueError from parse_ssl_verify_flags() when a token in the parsed verify-flags list is not an attribute of ssl.VerifyFlags. The function strips brackets, splits on comma, and validates each token via hasattr(VerifyFlags, flag). Any unknown name (including typos or version-mismatched constants) raises before the connection is built.

Solutions

  1. List the valid flags on your Python: python -c 'import ssl; print([x for x in dir(ssl.VerifyFlags) if not x.startswith("_")])' and use only those names.
  2. Pass ssl.VerifyFlags constants directly as a list (not a URL string) to avoid parsing pitfalls.
  3. Drop the unsupported flag if your Python version lacks it.

Example fix

// before
r = redis.asyncio.from_url('rediss://host?ssl_include_verify_flags=VERIFY_X509_STRICT,VERIFY_BOGUS')
// after
import ssl
r = redis.asyncio.Redis(host=h, ssl=True, ssl_include_verify_flags=[ssl.VerifyFlags.VERIFY_X509_STRICT])
Defensive patterns

Strategy: validation

Validate before calling

import ssl

def valid_verify_flags(names: list[str]) -> list:
    valid = {x for x in dir(ssl.VerifyFlags) if not x.startswith('_')}
    bad = [n for n in names if n not in valid]
    if bad:
        raise ValueError(f'Unsupported VerifyFlags: {bad}; valid: {sorted(valid)}')
    return [getattr(ssl.VerifyFlags, n) for n in names]

Type guard

def is_bad_verify_flag(exc: BaseException) -> bool:
    return isinstance(exc, ValueError) and 'ssl verify flag' in str(exc).lower()

Try / catch

from redis.asyncio.connection import parse_ssl_verify_flags

try:
    flags = parse_ssl_verify_flags(raw)
except ValueError as e:
    if 'ssl verify flag' in str(e).lower():
        flags = []  # or fall back to ssl.VerifyFlags constants
    else:
        raise

Prevention

When it happens

Trigger: Passing ssl_include_verify_flags / ssl_exclude_verify_flags through from_url as a query string like ?ssl_include_verify_flags=VERIFY_X509_STRICT,VERIFY_BOGUS, or passing a malformed list. Any token not present on the installed Python's ssl.VerifyFlags raises.

Common situations: Typo in a flag name; using a flag constant that exists in a newer Python (e.g. VERIFY_X509_PARTIAL_CHAIN) on an older interpreter; copy-pasting the C-level constant name instead of the Python attribute.

Understand the failure class

Related errors

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

Appendix: 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 6a6b581b48)