{"id":"2ced58bfb6fc5b41","repo":"redis/redis-py","slug":"redis-url-must-specify-one-of-the-following-scheme-2ced58","errorCode":null,"errorMessage":"Redis URL must specify one of the following schemes (redis://, rediss://, unix://)","messagePattern":"Redis URL must specify one of the following schemes \\(redis://, rediss://, unix://\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"redis/connection.py","lineNumber":2336,"sourceCode":"    \"max_connections\": int,\n    \"health_check_interval\": int,\n    \"ssl_check_hostname\": to_bool,\n    \"ssl_include_verify_flags\": parse_ssl_verify_flags,\n    \"ssl_exclude_verify_flags\": parse_ssl_verify_flags,\n    \"ssl_min_version\": int,\n    \"timeout\": float,\n    \"protocol\": int,\n    \"legacy_responses\": to_bool,\n}\n\n\ndef parse_url(url):\n    if not (\n        url.startswith(\"redis://\")\n        or url.startswith(\"rediss://\")\n        or url.startswith(\"unix://\")\n    ):\n        raise ValueError(\n            \"Redis URL must specify one of the following \"\n            \"schemes (redis://, rediss://, unix://)\"\n        )\n\n    url = urlparse(url)\n    kwargs = {}\n\n    for name, value in parse_qs(url.query).items():\n        if value and len(value) > 0:\n            # parse_qs() already percent-decodes query values, so use the value\n            # as-is; unquoting again here would double-decode (e.g. \"%2520\" ->\n            # \"%20\" -> \" \"). See issue #4208.\n            value = value[0]\n            parser = URL_QUERY_ARGUMENT_PARSERS.get(name)\n            if parser:\n                try:\n                    kwargs[name] = parser(value)\n                except (TypeError, ValueError):","sourceCodeStart":2318,"sourceCodeEnd":2354,"githubUrl":"https://github.com/redis/redis-py/blob/da03cdc7e8731092b13e395605c3c1fb2de25de1/redis/connection.py#L2318-L2354","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nclient = redis.Redis.from_url(\"localhost:6379\")\n\n# after\nclient = redis.Redis.from_url(\"redis://localhost:6379\")\n# or\nclient = redis.Redis(host=\"localhost\", port=6379)","handlingStrategy":"validation","validationCode":"SUPPORTED_SCHEMES = (\"redis://\", \"rediss://\", \"unix://\")\nif not url.startswith(SUPPORTED_SCHEMES):\n    raise ValueError(f\"URL must start with one of {SUPPORTED_SCHEMES}; got: {url!r}\")\n\nclient = redis.Redis.from_url(url)","typeGuard":"def is_supported_redis_url(url: str) -> bool:\n    return url.startswith((\"redis://\", \"rediss://\", \"unix://\"))","tryCatchPattern":"try:\n    client = redis.Redis.from_url(url)\nexcept ValueError as e:\n    if \"must specify one of the following schemes\" in str(e):\n        url = \"redis://\" + url.lstrip(\"/\")\n        client = redis.Redis.from_url(url)\n    else:\n        raise","preventionTips":["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."],"tags":["configuration","url-parsing","connection","validation"],"analyzedSha":"da03cdc7e8731092b13e395605c3c1fb2de25de1","analyzedAt":"2026-08-04T20:26:47.563Z","schemaVersion":2}