redis/redis-py · error · ValueError

Redis URL must specify one of the following schemes ({valid_

Error message

Redis URL must specify one of the following schemes ({valid_schemes})

What it means

Raised as a ValueError from parse_url() when the URL scheme is not one of 'redis', 'rediss', or 'unix'. The valid schemes string lists redis://, rediss://, unix://. Anything else (http://, rediss, missing ://, typos like redi://) lands in the else branch at line 1815.

Source

Thrown at redis/asyncio/connection.py:1817

        if parsed.hostname:
            kwargs["host"] = unquote(parsed.hostname)
        if parsed.port:
            kwargs["port"] = int(parsed.port)

        # If there's a path argument, use it as the db argument if a
        # querystring value wasn't specified
        if parsed.path and "db" not in kwargs:
            try:
                kwargs["db"] = int(unquote(parsed.path).replace("/", ""))
            except (AttributeError, ValueError):
                pass

        if parsed.scheme == "rediss":
            kwargs["connection_class"] = SSLConnection

    else:
        valid_schemes = "redis://, rediss://, unix://"
        raise ValueError(
            f"Redis URL must specify one of the following schemes ({valid_schemes})"
        )

    return kwargs


_CP = TypeVar("_CP", bound="ConnectionPool")


class ConnectionPoolInterface(ABC):
    @abstractmethod
    def get_protocol(self):
        pass

    @abstractmethod
    def reset(self) -> None:
        pass

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Use exactly 'redis://' (plaintext), 'rediss://' (TLS), or 'unix://' (UDS) as the scheme.
2. Double-check environment variables / config files that supply the URL.
3. Strip whitespace/newlines from the URL before passing it.
4. Log the scheme before constructing the client during debugging.

Example fix

// before
r = redis.asyncio.from_url("http://localhost:6379")

// after
r = redis.asyncio.from_url("redis://localhost:6379")

from urllib.parse import urlparse
VALID_SCHEMES = {"redis", "rediss", "unix"}
def valid_redis_url(url: str) -> bool:
    return urlparse(url).scheme in VALID_SCHEMES

def is_redis_scheme_url(url: str) -> bool:
    from urllib.parse import urlparse
    return urlparse(url).scheme in ("redis", "rediss", "unix")

try:
    r = redis.asyncio.from_url(url)
except ValueError as e:
    if "must specify one of the following schemes" in str(e):
        r = redis.asyncio.Redis(host="localhost", port=6379)  # sane default
    else:
        raise

When it happens

Trigger: Calling redis.asyncio.from_url(url) / Redis.from_url with a URL whose scheme is unrecognized: 'http://host', 'redi://host', 'rediss:host' (no //), 'tcp://host', an empty string, or a URL with no scheme at all.

Common situations: Env var misconfiguration (REDIS_URL=http://...); missing '://' ; typo in scheme; copying a URI from another database (postgres://, mongodb://) into a Redis config; secret-manager injecting the wrong format.

Related errors

• Invalid ssl verify flag: {flag}
• Invalid value for '{name}' in connection URL.
• Invalid SSL Certificate Requirements Flag: {cert_reqs}
• 'username' and 'password' cannot be passed along with 'crede
• protocol must be an integer

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