{"record":{"id":"5ecb20056fc06ec8","repo":"BerriAI/litellm","slug":"unexpected-responses-stream-payload","errorCode":null,"errorMessage":"Unexpected responses stream payload","messagePattern":"Unexpected responses stream payload","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/completion_extras/litellm_responses_transformation/handler.py","lineNumber":61,"sourceCode":"    def _is_preformatted_cached_chat_stream(result: Any) -> bool:\n        from litellm.litellm_core_utils.streaming_handler import CustomStreamWrapper\n\n        return isinstance(result, CustomStreamWrapper) and result.custom_llm_provider == \"cached_response\"\n\n    @staticmethod\n    def _coerce_response_object(\n        response_obj: Any,\n        hidden_params: dict | None,\n    ) -> \"ResponsesAPIResponse\":\n        if isinstance(response_obj, ResponsesAPIResponse):\n            response = response_obj\n        elif isinstance(response_obj, dict):\n            try:\n                response = ResponsesAPIResponse(**response_obj)\n            except Exception:\n                response = ResponsesAPIResponse.model_construct(**response_obj)\n        else:\n            raise ValueError(\"Unexpected responses stream payload\")\n\n        if hidden_params:\n            existing: Final = getattr(response, \"_hidden_params\", None)\n            if not isinstance(existing, dict) or not existing:\n                setattr(response, \"_hidden_params\", dict(hidden_params))\n            else:\n                for key, value in hidden_params.items():\n                    existing.setdefault(key, value)\n        return response\n\n    def _collect_response_from_stream(self, stream_iter: Any) -> \"ResponsesAPIResponse\":\n        for _ in stream_iter:\n            pass\n\n        completed: Final = getattr(stream_iter, \"completed_response\", None)\n        response_obj: Final = getattr(completed, \"response\", None) if completed else None\n        if response_obj is None:\n            raise ValueError(\"Stream ended without a completed response\")","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/completion_extras/litellm_responses_transformation/handler.py#L43-L79","documentation":"This handler bridges the Responses API to a completion-style stream by replaying the stream iterator and collecting its final completed_response. When the collected payload's response object is neither a ResponsesAPIResponse nor a dict (e.g. a string, bytes, or some provider-specific object), _coerce_response_object raises ValueError('Unexpected responses stream payload'). It is an internal invariant violation: upstream code produced a payload the bridge cannot convert.","triggerScenarios":"Using the responses-to-completion bridge (e.g. litellm.responses(...) with a completion-style consumer) where a provider transformation yields completed_response.response of an unexpected type; typically surfaces with nonstandard providers or custom transformation hooks.","commonSituations":"Beta/edge providers whose transformation layers return raw strings or provider objects instead of the expected dict/model; version skew between litellm core and a provider adapter.","solutions":["Update litellm — bridge payload handling is actively fixed across versions: pip install -U litellm","If the payload comes from a custom transformation, ensure it returns a dict or ResponsesAPIResponse on completed_response.response","Reproduce with litellm.responses(stream=True) against the same model/provider and inspect the type of stream.completed_response.response to identify the offending layer"],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":null,"typeGuard":"from litellm.types.responses import ResponsesAPIResponse\n\ndef is_coercible_response_payload(obj: Any) -> TypeGuard[ResponsesAPIResponse | dict]:\n    return isinstance(obj, (ResponsesAPIResponse, dict))","tryCatchPattern":"try:\n    result = bridge.collect(stream_iter)\nexcept ValueError as e:\n    if 'Unexpected responses stream payload' in str(e):\n        logger.error('Provider produced a non-standard completed response payload: %r', type(payload))\n    raise","preventionTips":["Update litellm when bridging new providers — payload coercion is actively maintained","In custom transformations, always materialize completed_response.response as a dict or ResponsesAPIResponse"],"tags":["responses-api","streaming","bridge","type-mismatch","internal"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}