{"record":{"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/d041d4d0fd48c3f0832084d33be16cf1c4835f85/aiohttp/web_ws.py#L675-L711","documentation":"Raised by WebSocketResponse.receive_str() as a WSMessageTypeError (a TypeError subclass) when the message returned by receive() is not of type WSMsgType.TEXT. receive_str() expects a text frame; receiving a BINARY, PING, PONG, CLOSE, CLOSING, CLOSED, or ERROR frame trips the guard. The %r formatting includes the actual frame type and payload for diagnosis.","triggerScenarios":"The peer sends a BINARY frame when the server calls receive_str(); the peer sends CLOSE/CLOSED mid-stream; receive_str() is used in a loop and a control frame arrives.","commonSituations":"Client and server disagree on text-vs-binary framing (e.g. client sends raw bytes for JSON); a disconnect causes a CLOSE frame that receive_str does not anticipate; using receive_str when the protocol actually transmits binary.","solutions":["Use receive() and switch on msg.type so you can handle TEXT, BINARY, and CLOSE/ERROR separately.","Catch WSMessageTypeError (importable from aiohttp) and treat non-text frames as a protocol error or close.","Align client and server on frame type — if the client sends binary, switch to receive_bytes()/receive_json_bytes()."],"exampleFix":"// before\nmsg = await ws.receive_str()  # raises on binary\n\n// after\nfrom aiohttp import WSMessageTypeError\ntry:\n    text = await ws.receive_str()\nexcept WSMessageTypeError:\n    msg = await ws.receive()\n    if msg.type == WSMsgType.BINARY:\n        text = msg.data.decode('utf-8')\n    else:\n        raise\n# or switch on type up front:\nmsg = await ws.receive()\nif msg.type == WSMsgType.TEXT: ...\nelif msg.type == WSMsgType.BINARY: ...","handlingStrategy":"try-catch","validationCode":"from aiohttp import WSMessageTypeError\ntry:\n    text = await ws.receive_str()\nexcept WSMessageTypeError:\n    msg = await ws.receive()\n    if msg.type == WSMsgType.TEXT:\n        text = msg.data\n    else:\n        raise","typeGuard":"def is_text_msg(msg) -> bool:\n    return msg.type is WSMsgType.TEXT","tryCatchPattern":"try:\n    text = await ws.receive_str()\nexcept WSMessageTypeError as e:\n    # peer sent non-text; decide whether to close or switch to binary handling\n    await ws.close(code=WSCloseCode.UNSUPPORTED_DATA, message=b'expected text')\n    raise","preventionTips":["Prefer receive() with a type dispatch over receive_str() in mixed protocols.","Document the expected frame type in your protocol and validate the peer honours it.","Catch WSMessageTypeError specifically (it subclasses TypeError)."],"tags":["websocket","receive","typing","protocol","typeerror"],"backgroundTag":null,"analyzedSha":"d041d4d0fd48c3f0832084d33be16cf1c4835f85","analyzedAt":"2026-08-11T20:44:15.550Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}