langchain-ai/langgraph · error · RuntimeError

Protocol command did not return a valid response.

Error message

Protocol command did not return a valid response.

What it means

Protocol-envelope check in the async HTTP transport: the POST to the commands endpoint returned 2xx, but the response body could not be parsed into the expected JSON envelope (missing or malformed response object). The server replied with something the transport cannot interpret as a protocol response.

Solutions

1. Check that the server is a LangGraph server version that supports the v3 thread-centric streaming protocol
2. Inspect the raw response body (use verbose/debug logging) to see what the server actually returned
3. Verify the commands URL/path is correct and not hitting a proxy or error page

When it happens

Trigger: Thrown at libs/sdk-py/langgraph_sdk/stream/transport/http.py:85 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of langchain-ai/langgraph@38031739e5 (2026-08-26). Data as JSON: /api/errors/cb185f6d2771921d. Report an issue: GitHub.

Appendix: source

Thrown at libs/sdk-py/langgraph_sdk/stream/transport/http.py:85

        Raises:
            httpx.HTTPStatusError: server returned >= 400.
            RuntimeError: the transport has been closed via `close()`.
            RuntimeError: server returned a response missing the protocol envelope.
        """
        if self._closed:
            raise RuntimeError("Protocol transport is closed.")
        # Merge default headers first so content-type always wins.
        merged_headers = {**self._default_headers, "content-type": "application/json"}
        response = await self._client.post(
            self._commands_url,
            content=orjson.dumps(command),
            headers=merged_headers,
        )
        response.raise_for_status()
        if response.status_code in (202, 204):
            return None
        if not response.content:
            raise RuntimeError("Protocol command did not return a valid response.")
        try:
            payload = orjson.loads(response.content)
        except orjson.JSONDecodeError as err:
            raise RuntimeError(
                "Protocol command did not return a valid response."
            ) from err
        if not isinstance(payload, dict) or "id" not in payload:
            raise RuntimeError("Protocol command did not return a valid response.")
        return payload

    def open_event_stream(self, params: dict[str, Any]) -> EventStreamHandle:
        """Open an independent filtered SSE event stream.

        Posts `params` as a SubscribeParams body to `/threads/{thread_id}/stream/events`.
        Returns an `EventStreamHandle` whose `events` async iterator yields typed
        `Event` dicts as the server emits them. `handle.ready` resolves on a 2xx
        response (rejects on HTTP error or transport failure before headers).

View on GitHub (pinned to 38031739e5)