{"record":{"id":"1dc331a52dd057d0","repo":"iflytek/astron-agent","slug":"websocketclientdataformaterror","errorCode":"WebSocketClientDataFormatError","errorMessage":"WebSocket 数据格式错误","messagePattern":"WebSocket 数据格式错误","errorType":"error_code","errorClass":"WebSocketClientException","httpStatus":null,"severity":"error","filePath":"core/plugin/aitools/common/clients/websockets_client.py","lineNumber":121,"sourceCode":"\n        self._tasks.append(self.task_factory.create(self._send_loop()))\n        self._tasks.append(self.task_factory.create(self._recv_loop()))\n\n    async def send(self, data: Any) -> None:\n        \"\"\"Send data to WebSocket server\"\"\"\n        self.send_data_list.append(data)\n        if not self._running:\n            raise WebSocketClientException.from_error_code(\n                CodeEnums.WebSocketClientNotConnectedError,\n                extra_message=\"WebSocket 未连接\",\n            )\n        else:\n            if isinstance(data, str) or isinstance(data, bytes):\n                await self.send_queue.put(data)\n            elif isinstance(data, dict) or isinstance(data, list):\n                await self.send_queue.put(json.dumps(data))\n            else:\n                raise WebSocketClientException.from_error_code(\n                    CodeEnums.WebSocketClientDataFormatError,\n                    extra_message=\"WebSocket 数据格式错误\",\n                )\n\n    async def recv(self) -> AsyncIterator[Any]:\n        \"\"\"Receive data from WebSocket server\"\"\"\n        while self._running:\n            try:\n                msg = await self.recv_queue.get()\n                if msg is None:\n                    break\n                if isinstance(msg, BaseException):\n                    raise msg\n                self.recv_data_list.append(msg)\n                yield msg\n            except WebSocketClientException:\n                raise\n            except Exception as e:","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/plugin/aitools/common/clients/websockets_client.py#L103-L139","documentation":"WebSocketClientDataFormatError is raised by send() when the payload is not str, bytes, dict, or list. Only those four types are supported; anything else (int, custom object, dataclass, None) is rejected because it cannot be queued or JSON-serialized safely.","triggerScenarios":"Calling await client.send(data) with a type outside {str, bytes, dict, list}, e.g. an int, a Pydantic model, a dataclass instance, a tuple, or None.","commonSituations":"Passing a Pydantic/dataclass response object straight to send() without model_dump(), sending numeric IDs directly, passing a tuple instead of a list after refactoring.","solutions":["Convert the payload before sending: json.dumps(...) to str, or model_dump()/dict for models.","Use dicts/lists for structured payloads so the client serializes them for you.","Add a caller-side type check for str/bytes/dict/list before send().","For binary payloads, ensure they are bytes, not bytearray/memoryview (wrap with bytes(...))."],"exampleFix":"// before\nawait client.send(my_pydantic_request)\n\n// after\nawait client.send(my_pydantic_request.model_dump())","handlingStrategy":"type-guard","validationCode":"def is_ws_payload(data) -> bool:\n    return isinstance(data, (str, bytes, dict, list))","typeGuard":"def as_ws_payload(data):\n    if isinstance(data, (str, bytes, dict, list)):\n        return data\n    if hasattr(data, 'model_dump'):\n        return data.model_dump()\n    raise TypeError(f'unsupported ws payload type: {type(data).__name__}')","tryCatchPattern":"try:\n    await client.send(data)\nexcept WebSocketClientException as e:\n    if '数据格式错误' in str(e):\n        await client.send(json.dumps(data, default=str))","preventionTips":["Serialize models with model_dump()/dict() before send","Keep payloads as dict/list/str/bytes at the boundary","Add a unit test asserting payload types accepted by send","Use json.dumps(default=str) for exotic types"],"tags":["websocket","serialization","type-mismatch"],"backgroundTag":"invalid-argument-format","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}