redis/redis-py · error · ValueError

Redis URL must specify one of the following schemes (redis:/

Error message

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

What it means

Raised as a ValueError by parse_url (connection.py:2331-2339) when the provided URL does not start with one of the three supported schemes: redis://, rediss:// (TLS), or unix:// (Unix domain socket). parse_url is called by ConnectionPool.from_url and Redis.from_url.

Source

Thrown at redis/connection.py:2336

    "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,
    "timeout": float,
    "protocol": int,
    "legacy_responses": to_bool,
}


def parse_url(url):
    if not (
        url.startswith("redis://")
        or url.startswith("rediss://")
        or url.startswith("unix://")
    ):
        raise ValueError(
            "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):

View on GitHub (pinned to da03cdc7e8)

Solutions

Prefix the URL with the correct scheme: redis:// for plaintext, rediss:// for TLS, unix:// for a socket.
If you only have host/port, use positional/keyword args instead of from_url: redis.Redis(host='localhost', port=6379).
Strip whitespace and check the URL string exactly before passing; the scheme match is case-sensitive.

Example fix

# before
client = redis.Redis.from_url("localhost:6379")

# after
client = redis.Redis.from_url("redis://localhost:6379")
# or
client = redis.Redis(host="localhost", port=6379)

Defensive patterns

Strategy: validation

Validate before calling

SUPPORTED_SCHEMES = ("redis://", "rediss://", "unix://")
if not url.startswith(SUPPORTED_SCHEMES):
    raise ValueError(f"URL must start with one of {SUPPORTED_SCHEMES}; got: {url!r}")

client = redis.Redis.from_url(url)

Type guard

def is_supported_redis_url(url: str) -> bool:
    return url.startswith(("redis://", "rediss://", "unix://"))

Try / catch

try:
    client = redis.Redis.from_url(url)
except ValueError as e:
    if "must specify one of the following schemes" in str(e):
        url = "redis://" + url.lstrip("/")
        client = redis.Redis.from_url(url)
    else:
        raise

Prevention

Centralize URL construction in a helper that always prefixes a scheme.
Strip and log the URL (redacting credentials) before passing to from_url.
Use redis.Redis(host=, port=) when you only have host/port to avoid scheme pitfalls.

When it happens

Trigger: Calling redis.Redis.from_url() / ConnectionPool.from_url() with a URL like 'localhost:6379', 'tcp://...', 'redis-sentinel://...', a bare host, or a URL with a typo in the scheme. The startswith checks at lines 2332-2334 are strict and case-sensitive.

Common situations: Dropping the scheme and passing 'host:port' directly to from_url (use the host= kwarg of redis.Redis() instead); using uppercase REDIS://; copy-pasting a Sentinel or cluster bus URL; env var with a stray leading space or missing scheme.

Related errors

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