{"record":{"id":"ef6ff816b2cc8575","repo":"BerriAI/litellm","slug":"unknown-message-type-message-str","errorCode":null,"errorMessage":"Unknown message type: {message_str}","messagePattern":"Unknown message type: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"litellm/llms/gemini/realtime/transformation.py","lineNumber":1521,"sourceCode":"            standalone_usage_metadata = json_message.get(\"usageMetadata\")\n            if isinstance(standalone_usage_metadata, dict):\n                self._pending_usage_metadata = standalone_usage_metadata\n            if not unhandled_known_keys:\n                return {\n                    \"response\": returned_message,\n                    \"current_output_item_id\": current_output_item_id,\n                    \"current_response_id\": current_response_id,\n                    \"current_delta_chunks\": current_delta_chunks,\n                    \"current_conversation_id\": current_conversation_id,\n                    \"current_item_chunks\": current_item_chunks,\n                    \"current_delta_type\": current_delta_type,\n                    \"session_configuration_request\": session_configuration_request,\n                }\n            if isinstance(message, bytes):\n                message_str = message.decode(\"utf-8\", errors=\"replace\")\n            else:\n                message_str = str(message)\n            raise ValueError(f\"Unknown message type: {message_str}\")\n\n        current_delta_chunks = self.update_current_delta_chunks(\n            transformed_message=returned_message,\n            current_delta_chunks=current_delta_chunks,\n        )\n        current_item_chunks = self.update_current_item_chunks(\n            transformed_message=returned_message,\n            current_item_chunks=current_item_chunks,\n        )\n\n        for msg in returned_message:\n            event_type = msg.get(\"type\") if isinstance(msg, dict) else \"unknown\"\n            verbose_logger.debug(\"Realtime Response Transform: OpenAI event=%s\", event_type)\n\n        return {\n            \"response\": returned_message,\n            \"current_output_item_id\": current_output_item_id,\n            \"current_response_id\": current_response_id,","sourceCodeStart":1503,"sourceCodeEnd":1539,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/gemini/realtime/transformation.py#L1503-L1539","documentation":"Raised at the tail of transform_realtime_response when the parsed JSON server frame matched none of the transformation branches and produced no returned messages — the code decodes it to a string (bytes-safe) and raises ValueError('Unknown message type: ...'). It is the catch-all for Gemini frames that are valid JSON but unrecognizable to this transformer version.","triggerScenarios":"A valid-JSON Gemini frame whose top-level shape is unknown: new event types, empty frames {}, error envelopes, or frames only partially covered by the installed litellm transformer.","commonSituations":"Gemini rolling out new realtime event types; API version mismatch (v1alpha frames against a v1beta-targeted transformer); error/notice frames from the infrastructure rather than the model.","solutions":["Upgrade litellm to the latest realtime transformer.","Catch and log the raw frame (it is embedded in the message) to identify what the server sent.","Skip unknown frames and keep the session alive; reconnect if the same frame type repeats and blocks progress."],"exampleFix":"# before\nout = config.transform_realtime_response(message=frame, ...)\n\n# after\ntry:\n    out = config.transform_realtime_response(message=frame, ...)\nexcept ValueError as e:\n    if 'Unknown message type' in str(e):\n        logger.info('Skipping unknown Gemini frame: %s', e)\n        out = {'returned_message': []}\n    else:\n        raise\n","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    out = config.transform_realtime_response(message=frame, ...)\nexcept ValueError as e:\n    if \"Unknown message type\" in str(e):\n        logger.info(\"Ignoring unrecognized Gemini frame: %s\", e)\n        out = {\"returned_message\": []}\n    else:\n        raise","preventionTips":["Log unknown frames (message embeds the raw payload) and monitor their frequency.","Upgrade litellm promptly after Gemini realtime API updates.","Design session loops to tolerate skipped frames so unknown types degrade gracefully."],"tags":["gemini","realtime","event-mapping","compatibility","unknown-frame"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}