BerriAI/litellm · error · ValueError

Unknown openai event: {openai_event}

Error message

Unknown openai event: {openai_event}

What it means

Raised near the end of transform_realtime_response when the frame WAS recognized and mapped to an OpenAIRealtimeEventTypes value, but that value did not match any branch of the transformation if/elif chain. The mapping table and the handler chain have drifted: an enum the lookup can return but no handler processes hits the else-raise.

Source

Thrown at litellm/llms/gemini/realtime/transformation.py:1494

                    "current_delta_chunks": current_delta_chunks,
                    "current_item_chunks": current_item_chunks,
                    "current_delta_type": current_delta_type,
                    "session_configuration_request": session_configuration_request,
                }
                _returned_message = self.handle_openai_modality_event(
                    openai_event,
                    json_message,
                    _modality_input,
                    delta_type="text" if "text" in openai_event.value else "audio",
                )
                returned_message.extend(_returned_message["returned_message"])
                current_output_item_id = _returned_message["current_output_item_id"]
                current_response_id = _returned_message["current_response_id"]
                current_conversation_id = _returned_message["current_conversation_id"]
                current_delta_chunks = _returned_message["current_delta_chunks"]
                current_delta_type = _returned_message["current_delta_type"]
            else:
                raise ValueError(f"Unknown openai event: {openai_event}")
        if len(returned_message) == 0:
            unhandled_known_keys: Final = [
                key
                for key in json_message
                if key in _KNOWN_GEMINI_TOP_LEVEL_KEYS
                and not (key == "serverContent" and server_content_handled)
                and not (key == "toolCall" and tool_call_handled)
            ]
            standalone_usage_metadata = json_message.get("usageMetadata")
            if isinstance(standalone_usage_metadata, dict):
                self._pending_usage_metadata = standalone_usage_metadata
            if not unhandled_known_keys:
                return {
                    "response": returned_message,
                    "current_output_item_id": current_output_item_id,
                    "current_response_id": current_response_id,
                    "current_delta_chunks": current_delta_chunks,
                    "current_conversation_id": current_conversation_id,

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Upgrade (or pin) litellm to a release where mapping and handlers are consistent.
2. Catch the ValueError per frame, log the openai_event name, and skip — the session usually remains usable.
3. Report the unmapped enum to the litellm issue tracker with the raw frame.

Example fix

# before
out = config.transform_realtime_response(message=frame, ...)

# after
try:
    out = config.transform_realtime_response(message=frame, ...)
except ValueError as e:
    if 'Unknown openai event' in str(e):
        logger.warning('Unhanded event enum, skipping frame: %s', e)
        out = {'returned_message': []}
    else:
        raise

try:
    out = config.transform_realtime_response(message=frame, ...)
except ValueError as e:
    if "Unknown openai event" in str(e):
        logger.warning("Unhandled mapped event enum; skipping frame: %s", e)
        out = {"returned_message": []}
    else:
        raise

When it happens

Trigger: A Gemini frame maps to an OpenAI event enum value (via the key-mapping search) that the big handler chain in transform_realtime_response does not implement — typically after a mapping entry is added without a matching handler, or vice versa, in a given litellm version.

Common situations: litellm version skew/bug between mapping and handlers; newly added event mappings in patch releases; using forked/custom transformations partially updated.

Related errors

• Unexpected delta type: {delta_type}
• Unknown openai event: {key}, value: {value}
• Unexpected part type: {part}
• Unexpected model turn event, no 'parts' key: {model_turn}
• Error updating current delta chunks: {e}, got transformed_me

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/36a5a8078e6bdfe0. Report an issue: GitHub.