iflytek/astron-agent · error · WebSocketClientException

WebSocketClientDataFormatError

WebSocketClientDataFormatError

Error message

WebSocket 数据格式错误

What it means

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.

Solutions

1. Convert the payload before sending: json.dumps(...) to str, or model_dump()/dict for models.
2. Use dicts/lists for structured payloads so the client serializes them for you.
3. Add a caller-side type check for str/bytes/dict/list before send().
4. For binary payloads, ensure they are bytes, not bytearray/memoryview (wrap with bytes(...)).

Example fix

// before
await client.send(my_pydantic_request)

// after
await client.send(my_pydantic_request.model_dump())

def is_ws_payload(data) -> bool:
    return isinstance(data, (str, bytes, dict, list))

def as_ws_payload(data):
    if isinstance(data, (str, bytes, dict, list)):
        return data
    if hasattr(data, 'model_dump'):
        return data.model_dump()
    raise TypeError(f'unsupported ws payload type: {type(data).__name__}')

try:
    await client.send(data)
except WebSocketClientException as e:
    if '数据格式错误' in str(e):
        await client.send(json.dumps(data, default=str))

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• CodeEnum.VARIABLE_NODE_EXECUTION_ERROR
• CodeEnums.ServiceResponseError
• convertTextErrorCodeToResponseEnum(listener.getErrorCode())
• Invalid host URL or authentication parameters
• INVALID_PARAMETER

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/1dc331a52dd057d0. Report an issue: GitHub.

Appendix: source

Thrown at core/plugin/aitools/common/clients/websockets_client.py:121

        self._tasks.append(self.task_factory.create(self._send_loop()))
        self._tasks.append(self.task_factory.create(self._recv_loop()))

    async def send(self, data: Any) -> None:
        """Send data to WebSocket server"""
        self.send_data_list.append(data)
        if not self._running:
            raise WebSocketClientException.from_error_code(
                CodeEnums.WebSocketClientNotConnectedError,
                extra_message="WebSocket 未连接",
            )
        else:
            if isinstance(data, str) or isinstance(data, bytes):
                await self.send_queue.put(data)
            elif isinstance(data, dict) or isinstance(data, list):
                await self.send_queue.put(json.dumps(data))
            else:
                raise WebSocketClientException.from_error_code(
                    CodeEnums.WebSocketClientDataFormatError,
                    extra_message="WebSocket 数据格式错误",
                )

    async def recv(self) -> AsyncIterator[Any]:
        """Receive data from WebSocket server"""
        while self._running:
            try:
                msg = await self.recv_queue.get()
                if msg is None:
                    break
                if isinstance(msg, BaseException):
                    raise msg
                self.recv_data_list.append(msg)
                yield msg
            except WebSocketClientException:
                raise
            except Exception as e:

View on GitHub (pinned to 5e758547a8)