aio-libs/aiohttp · error · ValueError

aiohttp only supports http(s) proxies (got: {proxy.scheme!r}

Error message

aiohttp only supports http(s) proxies (got: {proxy.scheme!r}).
See third-party libraries for other proxy schemes.

What it means

Raised as ValueError in ClientRequest when the configured proxy URL uses a scheme other than http or https. aiohttp's connector only knows how to tunnel through HTTP/HTTPS (CONNECT for HTTPS targets, plain forwarding for HTTP); SOCKS and other schemes require a third-party connector.

Source

Thrown at aiohttp/client_reqrep.py:1388

            and self.headers[hdrs.EXPECT].lower() == "100-continue"
        ):
            expect = True

        if expect:
            self._continue = self.loop.create_future()

    def _update_proxy(
        self,
        proxy: URL | None,
        proxy_headers: CIMultiDict[str] | None,
    ) -> None:
        if proxy is None:
            self.proxy = None
            self.proxy_headers = None
            return

        if proxy.scheme not in HTTP_AND_EMPTY_SCHEMA_SET:
            raise ValueError(
                f"aiohttp only supports http(s) proxies (got: {proxy.scheme!r}).\n"
                "See third-party libraries for other proxy schemes."
            )

        # URL-embedded credentials on the proxy map to Proxy-Authorization.
        if proxy.raw_user or proxy.raw_password:
            auth_header = encode_basic_auth(proxy.user or "", proxy.password or "")
            if proxy_headers is None:
                proxy_headers = CIMultiDict()
            proxy_headers.setdefault(hdrs.PROXY_AUTHORIZATION, auth_header)
            proxy = proxy.with_user(None)
        self.proxy = proxy
        self.proxy_headers = proxy_headers

    def _create_response(
        self,
        task: asyncio.Task[None] | None,
        stream_writer: AbstractStreamWriter,

View on GitHub (pinned to c0ef574e29)

Solutions

1. Use an http(s) proxy URL, e.g. 'http://proxy.local:8080'.
2. For SOCKS proxies install aiohttp-socks (or aiohttp_socks) and use its ProxyConnector.
3. Check the HTTP_PROXY / HTTPS_PROXY environment variables for a non-http scheme.

Example fix

# before
connector = aiohttp.TCPConnector()
await session.get(url, proxy='socks5://127.0.0.1:1080')
# after - use a SOCKS-aware connector
from aiohttp_socks import ProxyConnector
connector = ProxyConnector.from_url('socks5://127.0.0.1:1080')
async with aiohttp.ClientSession(connector=connector) as session:
    await session.get(url)

from yarl import URL
proxy = URL(proxy_url)
if proxy.scheme not in {'http', 'https'}:
    raise ValueError(f'aiohttp cannot use {proxy.scheme!r} proxies; use aiohttp_socks for SOCKS')

def is_http_proxy(proxy_url) -> bool:
    from yarl import URL
    return URL(proxy_url).scheme in {'http', 'https'}

When it happens

Trigger: Fires at line 1387-1391 when proxy.scheme is not in HTTP_AND_EMPTY_SCHEMA_SET. Triggered by passing proxy='socks5://127.0.0.1:1080', proxy='ftp://...', or similar non-http(s) proxy URLs.

Common situations: Using a SOCKS proxy (socks5h://) directly with aiohttp; env vars HTTPS_PROXY set to a socks URL; misconfigured corporate proxy scheme.

Related errors

• Digest auth error: Unsupported Quality of Protection (qop) v
• total timeout must be a positive number or None to disable,
• {url}
• Connection timeout to host {url}
• base_url must have a trailing '/'

AI-assisted analysis of aio-libs/aiohttp@c0ef574e29 (2026-08-04). Data as JSON: /data/errors/077f5c8b824602e8.json. Report an issue: GitHub.