encode/httpx · error · ValueError

Proxy protocol must be either 'http', 'https', 'socks5', or

Error message

Proxy protocol must be either 'http', 'https', 'socks5', or 'socks5h', but got {proxy.url.scheme!r}.

What it means

Raised by the synchronous HTTPTransport constructor when the supplied Proxy has a scheme that is none of 'http', 'https', 'socks5', 'socks5h'. The constructor branches on proxy.url.scheme and falls through to a ValueError for any other value. It is a programmer/config error surfaced at Client/transport construction time.

Source

Thrown at httpx/_transports/default.py:212

                ) from None

            self._pool = httpcore.SOCKSProxy(
                proxy_url=httpcore.URL(
                    scheme=proxy.url.raw_scheme,
                    host=proxy.url.raw_host,
                    port=proxy.url.port,
                    target=proxy.url.raw_path,
                ),
                proxy_auth=proxy.raw_auth,
                ssl_context=ssl_context,
                max_connections=limits.max_connections,
                max_keepalive_connections=limits.max_keepalive_connections,
                keepalive_expiry=limits.keepalive_expiry,
                http1=http1,
                http2=http2,
            )
        else:  # pragma: no cover
            raise ValueError(
                "Proxy protocol must be either 'http', 'https', 'socks5', or 'socks5h',"
                f" but got {proxy.url.scheme!r}."
            )

    def __enter__(self: T) -> T:  # Use generics for subclass support.
        self._pool.__enter__()
        return self

    def __exit__(
        self,
        exc_type: type[BaseException] | None = None,
        exc_value: BaseException | None = None,
        traceback: TracebackType | None = None,
    ) -> None:
        with map_httpcore_exceptions():
            self._pool.__exit__(exc_type, exc_value, traceback)

    def handle_request(

View on GitHub (pinned to b5addb64f0)

Solutions

1. Use one of the supported schemes: 'http', 'https', 'socks5', or 'socks5h' in the proxy URL.
2. If you have a SOCKS4 proxy, run/upgrade to a SOCKS5 server, or front it with an HTTP proxy.
3. Strip whitespace and validate the proxy string before passing it: assert proxy.split('://')[0] in {'http','https','socks5','socks5h'}.
4. If the value comes from an env var, log it (without credentials) to catch typos like 'socsk5'.

Example fix

// before
client = httpx.Client(proxy="socks4://127.0.0.1:1080")  # ValueError

// after
client = httpx.Client(proxy="socks5://127.0.0.1:1080")

from urllib.parse import urlparse

ALLOWED_PROXY_SCHEMES = {"http", "https", "socks5", "socks5h"}

def validate_proxy(proxy: str) -> str:
    scheme = urlparse(proxy).scheme.lower()
    if scheme not in ALLOWED_PROXY_SCHEMES:
        raise ValueError(
            f"Unsupported proxy scheme {scheme!r}; "
            f"must be one of {sorted(ALLOWED_PROXY_SCHEMES)}"
        )
    return proxy

client = httpx.Client(proxy=validate_proxy(my_proxy))

def is_supported_proxy(value: object) -> bool:
    if not isinstance(value, str):
        return False
    scheme = value.split("://", 1)[0].lower()
    return scheme in {"http", "https", "socks5", "socks5h"}

try:
    client = httpx.Client(proxy=proxy_str)
except ValueError as e:
    if "Proxy protocol must be" in str(e):
        log.error("Bad proxy config: %s", proxy_str.split("@")[-1])  # strip creds
    raise

When it happens

Trigger: Passing httpx.Client(proxy='ftp://...'), proxy='socks4://...', proxy='socks5://...' misspelled as 'socKS5://', or a Proxy object whose URL was built with an unsupported scheme. Also triggered by a typo in the ALL_PROXY env var (e.g. 'socsk5://').

Common situations: Confusing SOCKS4 (unsupported by httpx/httpcore) with SOCKS5; pasting a proxy URL from a tool that uses a non-standard scheme prefix; trailing slash or colon turning 'http' into 'http:'; case where env-derived proxy string has a stray scheme.

Related errors

• Using SOCKS proxy, but the 'socksio' package is not installe
• Proxy keys should use proper URL forms rather than plain sch
• Unknown scheme for proxy URL {url!r}
• URL too long
• Invalid URL component '{key}'

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