{"record":{"id":"00859b7916c3f68d","repo":"BerriAI/litellm","slug":"unknown-openai-event-key-value-value","errorCode":null,"errorMessage":"Unknown openai event: {key}, value: {value}","messagePattern":"Unknown openai event: (.+?), value: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/llms/gemini/realtime/transformation.py","lineNumber":1140,"sourceCode":"            # lookups to the current ``key``/``value`` pair — checking the\n            # whole ``json_message`` would let a sibling key (e.g.\n            # ``serverContent.turnComplete``) misclassify the event currently\n            # being processed (e.g. ``toolCall``).\n            for map_key, candidate_event in MAP_GEMINI_FIELD_TO_OPENAI_EVENT.items():\n                if map_key == key:\n                    openai_event = candidate_event\n                    break\n                if \".\" in map_key:\n                    prefix, _, nested_path = map_key.partition(\".\")\n                    if (\n                        prefix == key\n                        and isinstance(value, dict)\n                        and GeminiRealtimeConfig.get_nested_value(value, nested_path) is not None\n                    ):\n                        openai_event = candidate_event\n                        break\n        if openai_event is None:\n            raise ValueError(f\"Unknown openai event: {key}, value: {value}\")\n        return openai_event\n\n    def transform_realtime_response(\n        self,\n        message: str | bytes,\n        model: str,\n        logging_obj: LiteLLMLoggingObj,\n        realtime_response_transform_input: RealtimeResponseTransformInput,\n    ) -> RealtimeResponseTypedDict:\n        \"\"\"\n        Keep this state less - leave the state management (e.g. tracking current_output_item_id, current_response_id, current_conversation_id, current_delta_chunks) to the caller.\n        \"\"\"\n        try:\n            json_message: Final = json.loads(message)\n        except json.JSONDecodeError:\n            if isinstance(message, bytes):\n                message_str = message.decode(\"utf-8\", errors=\"replace\")\n            else:","sourceCodeStart":1122,"sourceCodeEnd":1158,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/llms/gemini/realtime/transformation.py#L1122-L1158","documentation":"Raised in the event-key lookup used by transform_realtime_response: given a Gemini server frame key and its value, the code searches a mapping table (including dotted nested-path rules via get_nested_value); if no OpenAI event mapping matches, it raises ValueError with the unknown key and value. It fires when Gemini emits a top-level event kind this litellm version has no translation for.","triggerScenarios":"Gemini realtime server sends a new top-level frame key (new server event type added by Google, or an uncommon event like goAway/sessionInfo) not present in the installed litellm mapping table.","commonSituations":"litellm version lagging a Gemini realtime API expansion; opting into preview/GA-Preview features that emit new frames; long-lived sessions receiving lifecycle frames the mapping never covered.","solutions":["Upgrade litellm to the latest version for new event mappings.","Catch the ValueError per frame and log/skip unknown events rather than dropping the session.","Pin model/API versions you have tested against so new frame kinds are not emitted."],"exampleFix":"# before\nresult = config.transform_realtime_response(message=frame, ...)\n\n# after\ntry:\n    result = config.transform_realtime_response(message=frame, ...)\nexcept ValueError as e:\n    if 'Unknown openai event' in str(e):\n        logger.info('Ignoring unmapped Gemini event: %s', e)\n        result = None\n    else:\n        raise\n","handlingStrategy":"try-catch","validationCode":"KNOWN_GEMINI_FRAME_KEYS = {\"serverContent\", \"toolCall\", \"setupComplete\", \"usageMetadata\"}\n\ndef is_known_frame(json_message: dict) -> bool:\n    return any(k in KNOWN_GEMINI_FRAME_KEYS for k in json_message)","typeGuard":"def is_known_frame(json_message: object) -> bool:\n    if not isinstance(json_message, dict):\n        return False\n    known = {\"serverContent\", \"toolCall\", \"setupComplete\", \"usageMetadata\"}\n    return any(k in known for k in json_message)","tryCatchPattern":"try:\n    out = config.transform_realtime_response(message=frame, ...)\nexcept ValueError as e:\n    if \"Unknown openai event\" in str(e) and \"value\" in str(e):\n        logger.info(\"Skipping unmapped Gemini event: %s\", e)\n        out = None\n    else:\n        raise","preventionTips":["Pin the Gemini realtime model/API version you tested with.","Upgrade litellm when Google announces realtime API additions.","Skip-and-log unknown events; alert when skip rate spikes (signals schema drift)."],"tags":["gemini","realtime","event-mapping","compatibility","versioning"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}