{"record":{"id":"12f47db00eeee1fa","repo":"aio-libs/aiohttp","slug":"invalid-response-status","errorCode":null,"errorMessage":"Invalid response status","messagePattern":"Invalid response status","errorType":"http","errorClass":"WSServerHandshakeError","httpStatus":null,"severity":"error","filePath":"aiohttp/client.py","lineNumber":1101,"sourceCode":"            )\n\n        # send request\n        resp = await self.request(\n            method,\n            url,\n            params=params,\n            headers=real_headers,\n            read_until_eof=False,\n            proxy=proxy,\n            ssl=ssl,\n            server_hostname=server_hostname,\n            proxy_headers=proxy_headers,\n        )\n\n        try:\n            # check handshake\n            if resp.status != 101:\n                raise WSServerHandshakeError(\n                    resp.request_info,\n                    resp.history,\n                    message=\"Invalid response status\",\n                    status=resp.status,\n                    headers=resp.headers,\n                )\n\n            if resp.headers.get(hdrs.UPGRADE, \"\").lower() != \"websocket\":\n                raise WSServerHandshakeError(\n                    resp.request_info,\n                    resp.history,\n                    message=\"Invalid upgrade header\",\n                    status=resp.status,\n                    headers=resp.headers,\n                )\n\n            if not resp._upgraded:\n                raise WSServerHandshakeError(","sourceCodeStart":1083,"sourceCodeEnd":1119,"githubUrl":"https://github.com/aio-libs/aiohttp/blob/d041d4d0fd48c3f0832084d33be16cf1c4835f85/aiohttp/client.py#L1083-L1119","documentation":"Raised as WSServerHandshakeError when the WebSocket upgrade response status is not 101 Switching Protocols. The server did not complete the handshake; common causes are auth failures, hitting a non-WebSocket endpoint, or a reverse proxy that doesn't forward the Upgrade headers.","triggerScenarios":"Calling session.ws_connect against a URL that is a plain HTTP page, requires authentication (401/403), doesn't exist (404), or whose proxy stripped the Upgrade headers (200 with HTML). resp.status != 101.","commonSituations":"Wrong scheme (ws:// vs wss://). Endpoint path is a REST URL, not a WS endpoint. Bearer/basic auth required and not supplied. Nginx/Apache in front of the WS server without Upgrade/Connection forwarding. TLS termination that drops headers.","solutions":["Verify the URL scheme and path point to the WS endpoint (often /ws or /socket).","Supply required auth via headers= or cookies= and confirm via curl with -i first.","Configure the reverse proxy to forward Upgrade and Connection headers.","Catch WSServerHandshakeError and inspect .status / .headers to diagnose."],"exampleFix":"// before\nawait session.ws_connect('https://example.com/api')  # not a WS endpoint -> raises\n// after\nasync with session.ws_connect('wss://example.com/ws', headers={'Authorization': 'Bearer ...'}) as ws:\n    ...","handlingStrategy":"try-catch","validationCode":"async def safe_ws_connect(session, url, **kw):\n    # preflight: confirm the endpoint speaks WebSocket via a HEAD/GET\n    async with session.get(url, allow_redirects=False) as r:\n        if r.status >= 400:\n            raise RuntimeError(f'endpoint returned {r.status}; not a WS endpoint?')\n    return await session.ws_connect(url, **kw)","typeGuard":"def looks_like_ws_url(url: str) -> bool:\n    return url.startswith('ws://') or url.startswith('wss://')","tryCatchPattern":"from aiohttp import WSServerHandshakeError\n\ntry:\n    ws = await session.ws_connect(url)\nexcept WSServerHandshakeError as e:\n    if e.message == 'Invalid response status':\n        # auth/path/proxy issue; inspect e.status, e.headers\n        raise RuntimeError(f'WS handshake failed with status {e.status}')\n    raise","preventionTips":["Confirm the endpoint and scheme (ws vs wss) with curl -i -H 'Connection: Upgrade' -H 'Upgrade: websocket'.","Supply required auth headers in ws_connect(headers=...).","Verify reverse-proxy Upgrade/Connection forwarding before relying on the endpoint."],"tags":["websocket","handshake","network"],"backgroundTag":null,"analyzedSha":"d041d4d0fd48c3f0832084d33be16cf1c4835f85","analyzedAt":"2026-08-11T20:44:15.550Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}