{"record":{"id":"077f5c8b824602e8","repo":"aio-libs/aiohttp","slug":"aiohttp-only-supports-http-s-proxies-got-proxy","errorCode":null,"errorMessage":"aiohttp only supports http(s) proxies (got: {proxy.scheme!r}).\nSee third-party libraries for other proxy schemes.","messagePattern":"aiohttp only supports http\\(s\\) proxies \\(got: (.+?)\\)\\.\nSee third-party libraries for other proxy schemes\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"aiohttp/client_reqrep.py","lineNumber":1388,"sourceCode":"            and self.headers[hdrs.EXPECT].lower() == \"100-continue\"\n        ):\n            expect = True\n\n        if expect:\n            self._continue = self.loop.create_future()\n\n    def _update_proxy(\n        self,\n        proxy: URL | None,\n        proxy_headers: CIMultiDict[str] | None,\n    ) -> None:\n        if proxy is None:\n            self.proxy = None\n            self.proxy_headers = None\n            return\n\n        if proxy.scheme not in HTTP_AND_EMPTY_SCHEMA_SET:\n            raise ValueError(\n                f\"aiohttp only supports http(s) proxies (got: {proxy.scheme!r}).\\n\"\n                \"See third-party libraries for other proxy schemes.\"\n            )\n\n        # URL-embedded credentials on the proxy map to Proxy-Authorization.\n        if proxy.raw_user or proxy.raw_password:\n            auth_header = encode_basic_auth(proxy.user or \"\", proxy.password or \"\")\n            if proxy_headers is None:\n                proxy_headers = CIMultiDict()\n            proxy_headers.setdefault(hdrs.PROXY_AUTHORIZATION, auth_header)\n            proxy = proxy.with_user(None)\n        self.proxy = proxy\n        self.proxy_headers = proxy_headers\n\n    def _create_response(\n        self,\n        task: asyncio.Task[None] | None,\n        stream_writer: AbstractStreamWriter,","sourceCodeStart":1370,"sourceCodeEnd":1406,"githubUrl":"https://github.com/aio-libs/aiohttp/blob/d041d4d0fd48c3f0832084d33be16cf1c4835f85/aiohttp/client_reqrep.py#L1370-L1406","documentation":"Raised by ClientRequest._update_proxy() when the proxy URL's scheme is not in HTTP_AND_EMPTY_SCHEMA_SET (i.e. not http, https, or empty). aiohttp's client only speaks HTTP(S) proxying (CONNECT for HTTPS, direct forwarding for HTTP); SOCKS or other schemes require a third-party library. The error includes the offending scheme to aid diagnosis.","triggerScenarios":"Passing proxy='socks5://127.0.0.1:1080' or proxy='ftp://...' to session.request / ClientSession(proxy=...). The scheme check fails and ValueError is raised at request setup.","commonSituations":"Using a SOCKS proxy URL with aiohttp directly (unsupported); copy-paste of a proxy URL intended for requests/urllib3 with socks support; mis-typed scheme ('httpd://'); expecting aiohttp to support arbitrary proxy schemes.","solutions":["Use an http:// or https:// proxy URL with aiohttp.","For SOCKS proxies, install aiohttp-socks (or aiohttp_socks) and use its wrapper, which handles SOCKS4/5.","Verify the scheme spelling — a missing/typo'd scheme triggers the same error.","If you must route through SOCKS, run a local HTTP-to-SOCKS bridge and point aiohttp at it over http://."],"exampleFix":"# before\nawait session.get(url, proxy='socks5://127.0.0.1:1080')  # ValueError\n\n# after — use aiohttp-socks for SOCKS\nfrom aiohttp_socks import ProxyConnector\nconnector = ProxyConnector.from_url('socks5://127.0.0.1:1080')\nasync with aiohttp.ClientSession(connector=connector) as session:\n    await session.get(url)\n# or, for an HTTP proxy:\nawait session.get(url, proxy='http://127.0.0.1:8080')","handlingStrategy":"validation","validationCode":"from yarl import URL\n\ndef http_proxy(url):\n    u = URL(url) if not isinstance(url, URL) else url\n    if u.scheme not in ('http', 'https', ''):\n        raise ValueError(f'aiohttp supports only http(s) proxies; got scheme {u.scheme!r}')\n    return u","typeGuard":"from yarl import URL\ndef is_http_proxy(url) -> bool:\n    try:\n        u = URL(url) if not isinstance(url, URL) else url\n    except Exception:\n        return False\n    return u.scheme in ('http', 'https', '')","tryCatchPattern":"try:\n    await session.get(url, proxy=proxy_url)\nexcept ValueError as e:\n    if 'only supports http(s) proxies' in str(e):\n        # switch to aiohttp_socks for SOCKS, or use an http proxy\n        from aiohttp_socks import ProxyConnector\n        connector = ProxyConnector.from_url(proxy_url)\n        async with aiohttp.ClientSession(connector=connector) as s:\n            await s.get(url)\n    else:\n        raise","preventionTips":["Use only http:// or https:// proxy URLs with aiohttp's native proxy param.","Install aiohttp-socks for SOCKS4/5 support instead of passing socks:// URLs.","Validate proxy scheme at config-load time."],"tags":["client","proxy","configuration","http","socks"],"backgroundTag":null,"analyzedSha":"d041d4d0fd48c3f0832084d33be16cf1c4835f85","analyzedAt":"2026-08-11T20:44:15.550Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}