{"id":"4d1621b6fee91575","repo":"aio-libs/aiohttp","slug":"received-message-msg-type-msg-data-r-is-not-ws-4d1621","errorCode":null,"errorMessage":"Received message {msg.type}:{msg.data!r} is not WSMsgType.TEXT","messagePattern":"Received message (.+?):(.+?) is not WSMsgType\\.TEXT","errorType":"exception","errorClass":"WSMessageTypeError","httpStatus":null,"severity":"error","filePath":"aiohttp/web_ws.py","lineNumber":693,"sourceCode":"\n    @overload\n    async def receive_str(\n        self: \"WebSocketResponse[Literal[False]]\", *, timeout: float | None = None\n    ) -> bytes: ...\n\n    @overload\n    async def receive_str(\n        self: \"WebSocketResponse[_DecodeText]\", *, timeout: float | None = None\n    ) -> str | bytes: ...\n\n    async def receive_str(self, *, timeout: float | None = None) -> str | bytes:\n        \"\"\"Receive TEXT message.\n\n        Returns str when decode_text=True (default), bytes when decode_text=False.\n        \"\"\"\n        msg = await self.receive(timeout)\n        if msg.type is not WSMsgType.TEXT:\n            raise WSMessageTypeError(\n                f\"Received message {msg.type}:{msg.data!r} is not WSMsgType.TEXT\"\n            )\n        return msg.data\n\n    async def receive_bytes(self, *, timeout: float | None = None) -> bytes:\n        msg = await self.receive(timeout)\n        if msg.type is not WSMsgType.BINARY:\n            raise WSMessageTypeError(\n                f\"Received message {msg.type}:{msg.data!r} is not WSMsgType.BINARY\"\n            )\n        return msg.data\n\n    @overload\n    async def receive_json(\n        self: \"WebSocketResponse[Literal[True]]\",\n        *,\n        loads: JSONDecoder = ...,\n        timeout: float | None = None,","sourceCodeStart":675,"sourceCodeEnd":711,"githubUrl":"https://github.com/aio-libs/aiohttp/blob/c0ef574e29109210e96e652771ae4e7b88615fa4/aiohttp/web_ws.py#L675-L711","documentation":"Raised by WebSocketResponse.receive_str() as a WSMessageTypeError (a TypeError subclass) when the received message is not a TEXT frame. receive_str() calls receive() then asserts msg.type is WSMsgType.TEXT; a BINARY frame, or a control/close message returned by receive(), fails the check. The message includes the actual type and data for diagnostics.","triggerScenarios":"Calling `await ws.receive_str()` when the peer sent a BINARY frame, or when receive() returned a CLOSE/CLOSING/CLOSED/PING/PONG control message. The check at aiohttp/web_ws.py:692-695 raises.","commonSituations":"Peer sends binary data but the server assumes text; mixing JSON-as-text and binary attachments on the same socket; receive_str() called after the connection started closing, so receive() returns a CLOSE sentinel; a client that switches frame types mid-stream.","solutions":["Use the generic receive() and branch on msg.type so you can handle BINARY and control frames.","Check `msg.type` before treating data as text; only call receive_str() when you know the peer sends TEXT.","Catch WSMessageTypeError (from aiohttp.client_exceptions) to recover when a non-text frame arrives.","Coordinate the wire protocol with the peer so both sides agree on text vs binary."],"exampleFix":"# before\nasync for _ in ws:\n    text = await ws.receive_str()  # raises on BINARY/CLOSE\n\n# after\nasync for msg in ws:\n    if msg.type == WSMsgType.TEXT:\n        handle_text(msg.data)\n    elif msg.type == WSMsgType.BINARY:\n        handle_binary(msg.data)","handlingStrategy":"try-catch","validationCode":"from aiohttp import WSMsgType\nfrom aiohttp.client_exceptions import WSMessageTypeError\n\nasync def receive_text(ws):\n    msg = await ws.receive()\n    if msg.type is WSMsgType.TEXT:\n        return msg.data\n    return None","typeGuard":"from aiohttp import WSMsgType\n\ndef is_text(msg) -> bool:\n    return msg.type is WSMsgType.TEXT","tryCatchPattern":"from aiohttp.client_exceptions import WSMessageTypeError\n\ntry:\n    text = await ws.receive_str()\nexcept WSMessageTypeError:\n    # peer sent a non-text frame; handle via generic receive()\n    msg = await ws.receive()","preventionTips":["Use generic receive() and branch on msg.type when the protocol mixes frame types.","Catch WSMessageTypeError at boundaries where a non-text frame is recoverable.","Agree on text vs binary with the peer up front."],"tags":["websocket","server","types","receive"],"analyzedSha":"c0ef574e29109210e96e652771ae4e7b88615fa4","analyzedAt":"2026-08-04T19:51:05.467Z","schemaVersion":2}