encode/httpx · error · ValueError

Unknown scheme for proxy URL {url!r}

Error message

Unknown scheme for proxy URL {url!r}

What it means

Raised as ValueError by Proxy.__init__ when url.scheme is not one of http, https, socks5, socks5h. httpx only supports these proxy schemes; anything else (or a URL missing a scheme) is rejected at construction.

Source

Thrown at httpx/_config.py:214

            f"max_keepalive_connections={self.max_keepalive_connections}, "
            f"keepalive_expiry={self.keepalive_expiry})"
        )


class Proxy:
    def __init__(
        self,
        url: URL | str,
        *,
        ssl_context: ssl.SSLContext | None = None,
        auth: tuple[str, str] | None = None,
        headers: HeaderTypes | None = None,
    ) -> None:
        url = URL(url)
        headers = Headers(headers)

        if url.scheme not in ("http", "https", "socks5", "socks5h"):
            raise ValueError(f"Unknown scheme for proxy URL {url!r}")

        if url.username or url.password:
            # Remove any auth credentials from the URL.
            auth = (url.username, url.password)
            url = url.copy_with(username=None, password=None)

        self.url = url
        self.auth = auth
        self.headers = headers
        self.ssl_context = ssl_context

    @property
    def raw_auth(self) -> tuple[bytes, bytes] | None:
        # The proxy authentication as raw bytes.
        return (
            None
            if self.auth is None
            else (self.auth[0].encode("utf-8"), self.auth[1].encode("utf-8"))

View on GitHub (pinned to b5addb64f0)

Solutions

1. Use a supported scheme: http://, https://, socks5://, or socks5h://.
2. For SOCKS4 proxies, switch the proxy server to SOCKS5 or use socks5h://.
3. Ensure the URL has an explicit scheme (add 'http://' if it is an HTTP proxy).

Example fix

// before
httpx.Proxy("socks4://host:1080")  # ValueError
// after
httpx.Proxy("socks5://host:1080")

import httpx
SUPPORTED = {"http", "https", "socks5", "socks5h"}
parsed = httpx.URL(proxy_url)
if parsed.scheme not in SUPPORTED:
    raise ValueError(f"unsupported proxy scheme {parsed.scheme!r}; use one of {sorted(SUPPORTED)}")
proxy = httpx.Proxy(proxy_url)

import httpx

def proxy_scheme_supported(url: str) -> bool:
    return httpx.URL(url).scheme in {"http", "https", "socks5", "socks5h"}

try:
    proxy = httpx.Proxy(proxy_url)
except ValueError as exc:
    raise ValueError(f"Bad proxy URL {proxy_url!r}: {exc}") from exc

When it happens

Trigger: Constructing httpx.Proxy('socks4://host:1080'), httpx.Proxy('ftp://host'), or httpx.Proxy('host:8080') (no scheme).

Common situations: Pointing at a SOCKS4 proxy (unsupported); an FTP/other proxy; a bare host:port string with no scheme; typo in the proxy URL.

Related errors

• Proxy protocol must be either 'http', 'https', 'socks5', or
• Proxy keys should use proper URL forms rather than plain sch
• Invalid "auth" argument: {auth!r}
• Using http2=True, but the 'h2' package is not installed. Mak
• httpx.Timeout must either include a default, or set all four

AI-assisted analysis of encode/httpx@b5addb64f0 (2026-08-04). Data as JSON: /data/errors/d4508c47a13d4149.json. Report an issue: GitHub.