BerriAI/litellm · error · ValueError

Unknown openai event: {key}, value: {value}

Error message

Unknown openai event: {key}, value: {value}

What it means

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.

Source

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

            # lookups to the current ``key``/``value`` pair — checking the
            # whole ``json_message`` would let a sibling key (e.g.
            # ``serverContent.turnComplete``) misclassify the event currently
            # being processed (e.g. ``toolCall``).
            for map_key, candidate_event in MAP_GEMINI_FIELD_TO_OPENAI_EVENT.items():
                if map_key == key:
                    openai_event = candidate_event
                    break
                if "." in map_key:
                    prefix, _, nested_path = map_key.partition(".")
                    if (
                        prefix == key
                        and isinstance(value, dict)
                        and GeminiRealtimeConfig.get_nested_value(value, nested_path) is not None
                    ):
                        openai_event = candidate_event
                        break
        if openai_event is None:
            raise ValueError(f"Unknown openai event: {key}, value: {value}")
        return openai_event

    def transform_realtime_response(
        self,
        message: str | bytes,
        model: str,
        logging_obj: LiteLLMLoggingObj,
        realtime_response_transform_input: RealtimeResponseTransformInput,
    ) -> RealtimeResponseTypedDict:
        """
        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.
        """
        try:
            json_message: Final = json.loads(message)
        except json.JSONDecodeError:
            if isinstance(message, bytes):
                message_str = message.decode("utf-8", errors="replace")
            else:

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Upgrade litellm to the latest version for new event mappings.
2. Catch the ValueError per frame and log/skip unknown events rather than dropping the session.
3. Pin model/API versions you have tested against so new frame kinds are not emitted.

Example fix

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

# after
try:
    result = config.transform_realtime_response(message=frame, ...)
except ValueError as e:
    if 'Unknown openai event' in str(e):
        logger.info('Ignoring unmapped Gemini event: %s', e)
        result = None
    else:
        raise

KNOWN_GEMINI_FRAME_KEYS = {"serverContent", "toolCall", "setupComplete", "usageMetadata"}

def is_known_frame(json_message: dict) -> bool:
    return any(k in KNOWN_GEMINI_FRAME_KEYS for k in json_message)

def is_known_frame(json_message: object) -> bool:
    if not isinstance(json_message, dict):
        return False
    known = {"serverContent", "toolCall", "setupComplete", "usageMetadata"}
    return any(k in known for k in json_message)

try:
    out = config.transform_realtime_response(message=frame, ...)
except ValueError as e:
    if "Unknown openai event" in str(e) and "value" in str(e):
        logger.info("Skipping unmapped Gemini event: %s", e)
        out = None
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unexpected part type: {part}
• Unknown openai event: {openai_event}
• Unknown message type: {message_str}
• Unexpected model turn event, no 'parts' key: {model_turn}
• Unexpected delta type: {delta_type}

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