fix(google): improve error message for model/API mismatch in Realtime API #4611

cdutr · 2026-01-25T02:48:15Z

Summary

This PR improves error messages when users accidentally configure a Gemini API model with VertexAI (or vice versa) in the Google Realtime plugin. Currently, users receive a cryptic WebSocket 1008 policy violation error that doesn't explain the root cause.

Problem

When using the Google Realtime plugin with incorrect model/API combinations:

Users get a confusing error: websockets.exceptions.ConnectionClosedError: received 1008 (policy violation)
The error doesn't explain that the model name doesn't match the API being used
Users spend significant time debugging WebSocket configurations instead of fixing the simple model name issue
This is a common pain point (see issue Audio quality issue with sip outbound call #4026 and related reports)

Example Scenario

A user tries to use VertexAI with a Gemini API model name:

model = google.realtime.RealtimeModel(
    model="gemini-2.5-flash-native-audio-preview-09-2025",  # Gemini API model
    vertexai=True,  # But using VertexAI
)

Current error:

websockets.exceptions.ConnectionClosedError: received 1008 (policy violation)

After this fix:

Failed to connect to Gemini Live

Hint: Model 'gemini-2.5-flash-native-audio-preview-09-2025' appears to be a Gemini API model,
but VertexAI is enabled. VertexAI requires different model names (prefixed with 'gemini-live-').
Try using model='gemini-live-2.5-flash-preview-native-audio-09-2025' instead.

Solution

Added a helper function _get_model_mismatch_hint() that:

Detects WebSocket 1008 policy violation errors
Checks if the model name pattern matches the API being used
Returns a helpful hint with the suggested correct model name
Only activates on actual 1008 errors (non-intrusive approach)

The hint is appended to both:

Logger error messages
Raised APIConnectionError exceptions

This provides immediate, actionable feedback without blocking any valid configurations or making assumptions about future model naming patterns.

Testing

Verified hint appears for Gemini API models + VertexAI
Verified hint appears for VertexAI models + Gemini API
Verified no hint for correct configurations
Verified no hint for non-1008 errors
Verified correct model suggestions for September and December 2025 models

Fixes livekit/livekit#4026

Summary by CodeRabbit

New Features
- Added model/API compatibility validation to detect mismatched model vs API choices.
Bug Fixes
- Improved error messages for connection failures with contextual hints for WebSocket policy violations and retry paths.
- Error logs now suggest configuration adjustments to resolve detected model/API mismatches.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

… API When users configure a Gemini API model (e.g., gemini-2.5-flash-native-audio-preview-09-2025) with VertexAI, or vice versa, they receive a cryptic WebSocket 1008 policy violation error. This makes it difficult to diagnose the root cause. This change detects 1008 errors that likely indicate a model/API mismatch and appends a helpful hint to the error message, suggesting the correct model name to use. The hint only appears when: - A WebSocket 1008 policy violation occurs - The model name pattern doesn't match the API being used Example improved error: ``` Failed to connect to Gemini Live Hint: Model 'gemini-2.5-flash-native-audio-preview-09-2025' appears to be a Gemini API model, but VertexAI is enabled. VertexAI requires different model names (prefixed with 'gemini-live-'). Try using model='gemini-live-2.5-flash-preview-native-audio-09-2025' instead. ``` Fixes: livekit/livekit#4026

CLAassistant · 2026-01-25T02:48:22Z

All committers have signed the CLA.

coderabbitai · 2026-01-25T02:48:44Z

📝 Walkthrough

Walkthrough

Added model/API compatibility checks and contextual error hints to the Google realtime plugin: introduced KNOWN_VERTEXAI_MODELS and KNOWN_GEMINI_API_MODELS, added _validate_model_api_match and _get_1008_error_hint helpers, run validation before options construction, and append hint text to logged/raised errors (including WebSocket 1008 and API connection errors).

Changes

Cohort / File(s)	Summary
Realtime model validation & error hints `livekit-plugins/livekit-plugins-google/livekit/plugins/google/realtime/realtime_api.py`	Added `KNOWN_VERTEXAI_MODELS` and `KNOWN_GEMINI_API_MODELS` constants; implemented `_validate_model_api_match(model: str, use_vertexai: bool) -> None` to enforce model/API alignment; implemented `_get_1008_error_hint(error_message: str) -> str

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 I hopped through code with ears up high,
Found models that clashed and made users cry.
I added checks, a hint or two,
Now Vertex and Gemini know what to do.
🥕✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: improving error messages for model/API mismatch in the Google Realtime API, which is the core focus of the changeset.
Linked Issues check	✅ Passed	The PR implements model/API mismatch validation and enhanced error hints as required by issue `#4026`, detecting Gemini API models used with VertexAI and providing contextual guidance.
Out of Scope Changes check	✅ Passed	All changes are focused on model/API mismatch detection and error messaging in the Realtime API, directly addressing the issue objective without introducing unrelated modifications.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 03d9750 and 3c296b1.

📒 Files selected for processing (1)

livekit-plugins/livekit-plugins-google/livekit/plugins/google/realtime/realtime_api.py

🧰 Additional context used

📓 Path-based instructions (1)

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

**/*.py: Format code with ruff
Run ruff linter and auto-fix issues
Run mypy type checker in strict mode
Maintain line length of 100 characters maximum
Ensure Python 3.9+ compatibility
Use Google-style docstrings

Files:

livekit-plugins/livekit-plugins-google/livekit/plugins/google/realtime/realtime_api.py

🧬 Code graph analysis (1)

livekit-plugins/livekit-plugins-google/livekit/plugins/google/realtime/realtime_api.py (2)

livekit-agents/livekit/agents/llm/llm.py (1)

model (99-108)

livekit-agents/livekit/agents/_exceptions.py (1)

APIConnectionError (84-88)

🔇 Additional comments (6)

livekit-plugins/livekit-plugins-google/livekit/plugins/google/realtime/realtime_api.py (6)

46-64: LGTM! Well-structured model constants.

The use of frozenset for immutability is appropriate. The documentation links will help maintainers keep these lists updated as Google releases new models.

67-90: LGTM! Clean fail-fast validation.

The function correctly validates known model/API mismatches and provides actionable error messages with example model names. Silently passing unknown models is the right design choice to avoid breaking future model releases.

92-113: LGTM! Correct 1008 error detection logic.

The condition correctly uses De Morgan's law to return a hint when either "1008" or "policy violation" is present in the error message. The case-insensitive check for "policy violation" is a good detail.

326-327: LGTM! Correct placement for fail-fast validation.

The validation is appropriately placed after determining use_vertexai and before constructing _RealtimeOptions, ensuring early failure with a clear error message.

828-843: LGTM! Clean error handling with contextual hints.

The hint is computed once and consistently applied to both logging and the raised exception. The exc_info=e parameter ensures stack traces are preserved in logs.

845-850: LGTM! Consistent error handling for retry exhaustion.

The pattern mirrors the earlier error path, maintaining consistency. The retry count in the message provides useful debugging context.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

davidzhao · 2026-01-26T01:11:58Z

livekit-plugins/livekit-plugins-google/livekit/plugins/google/realtime/realtime_api.py

+    is_vertexai_model = model.startswith("gemini-live-")
+    is_gemini_api_model = model.startswith(("gemini-2.", "gemini-1."))
+
+    if use_vertexai and is_gemini_api_model:


this logic doesn't seem very robust. we do not know how google is going to name their future models.

if you intend to do this, I would suggest:

keeping a list known of vertex models and another list of gemini

when specifically detect for mismatch, and throw an exception if a user is using vertext with gemini and vice versa

alternatively, translating the error code and log a clear message (this model isn't supported)

Good, it makes sense. Will adapt and resubmit. Thanks for the review!

Hi David, the first solutions was indeed too specific and made assumptions about future model naming patterns.

I refactored it to be more generic:

Added KNOWN_VERTEXAI_MODELS and KNOWN_GEMINI_API_MODELS as explicit frozensets with the models we know today

Created _validate_model_api_match() that checks if the model is in the wrong list and raises a ValueError right away in __init__ - so devs get a clear error before even trying to connect

Simplified the 1008 error hint to just be a generic message for unknown models that slip through

The idea is: if we know the model, fail fast with a clear message. If we don't know it, let it through and give a helpful hint if it fails with 1008.

I tried to optimize for developer experience, getting a ValueError at initialization is way better than debugging a cryptic WebSocket error later.

Let me know if you think it's overcomplicated or not generic enough. Happy to iterate on it!

This is my first time contributing to the project, so I picked a small issue to learn the process and get to know the maintainers and other contributors. Really appreciate your feedback, it helped me understand the codebase better. Looking forward to more reviews!

Address review feedback by: - Adding KNOWN_VERTEXAI_MODELS and KNOWN_GEMINI_API_MODELS frozensets with explicit lists of known models - Adding _validate_model_api_match() to raise ValueError early in __init__ when a known model is used with the wrong API configuration - Simplifying the 1008 error hint to be generic (for unknown models) This approach is more robust because it: - Doesn't make assumptions about future model naming patterns - Fails fast at initialization for known mismatches - Still provides helpful hints for unknown models on 1008 errors

davidzhao requested changes Jan 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(google): improve error message for model/API mismatch in Realtime API #4611

fix(google): improve error message for model/API mismatch in Realtime API #4611

Uh oh!

cdutr commented Jan 25, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

CLAassistant commented Jan 25, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 25, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

davidzhao Jan 26, 2026

Uh oh!

cdutr Jan 26, 2026

Uh oh!

cdutr Jan 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fix(google): improve error message for model/API mismatch in Realtime API #4611

Are you sure you want to change the base?

fix(google): improve error message for model/API mismatch in Realtime API #4611

Uh oh!

Conversation

cdutr commented Jan 25, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Problem

Example Scenario

Solution

Testing

Summary by CodeRabbit

Uh oh!

CLAassistant commented Jan 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Jan 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

davidzhao Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

cdutr Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

cdutr Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cdutr commented Jan 25, 2026 •

edited by coderabbitai bot

Loading

CLAassistant commented Jan 25, 2026 •

edited

Loading

coderabbitai bot commented Jan 25, 2026 •

edited

Loading