Gemini TTS: Addressing 500 errors #679
Description
Gemini TTS 500 INTERNAL Error — Diagnostic Guide
Error Signature
google.genai.errors.ServerError: 500 INTERNAL.
{'error': {'code': 500, 'message': 'An internal error has occurred.
Please retry or report in https://developers.generativeai.google/guide/troubleshooting',
'status': 'INTERNAL'}}
Root Causes
1. Outdated google-genai SDK
Symptoms: TTS calls that previously worked start failing with 500 across all languages/voices.
Fix:
uv add google-genai --upgrade
Why: Google frequently updates the Gemini API. Older SDK versions may send request formats the API no longer accepts, resulting in opaque 500s instead of proper deprecation errors.
2. Unsupported Language Code
Symptoms: 500 only for specific languages (e.g., od-IN for Odia).
Diagnosis: Check if the language code is in the supported list:
en-IN, hi-IN, bn-IN, ta-IN, te-IN, mr-IN, gu-IN, kn-IN, ml-IN, pa-IN, sd-IN
Fix: Use a supported BCP-47 language code, or omit language entirely to let Gemini auto-detect from the text script.
3. Invalid Voice + Language Combination
Symptoms: 500 with a valid language but specific voice.
Diagnosis: Not all Gemini voices support all languages. Current supported voices: Kore, Orus, Leda, Charon.
Fix: Try a different voice (default: Kore) or test the combination in Google AI Studio.
4. Deprecated or Renamed Model
Symptoms: 500 across all requests regardless of language/voice.
Diagnosis: Gemini TTS models are in preview and may be renamed or rotated. Current known models:
gemini-2.5-pro-preview-ttsgemini-2.5-flash-preview-tts
Fix: Verify model availability at Gemini model docs and update SUPPORTED_MODELS in app/models/llm/request.py.
Quick Triage Checklist
| Step | Action | Pass? |
|---|---|---|
| 1 | Update google-genai SDK to latest | ☐ |
| 2 | Test with model=gemini-2.5-flash-preview-tts, voice=Kore, language=en-IN | ☐ |
| 3 | If step 2 works, narrow down by changing one param at a time | ☐ |
| 4 | If step 2 fails, check Google AI Status for outages | ☐ |
| 5 | Test directly in Google AI Studio to isolate SDK vs API issue | ☐ |
Error Signature
google.genai.errors.ServerError: 500 INTERNAL.
{'error': {'code': 500, 'message': 'An internal error has occurred.
Please retry or report in https://developers.generativeai.google/guide/troubleshooting',
'status': 'INTERNAL'}}
Root Causes
1. Outdated google-genai SDK
Symptoms: TTS calls that previously worked start failing with 500 across all languages/voices.
Fix:
uv add google-genai --upgradeWhy: Google frequently updates the Gemini API. Older SDK versions may send request formats the API no longer accepts, resulting in opaque 500s instead of proper deprecation errors.
2. Unsupported Language Code
Symptoms: 500 only for specific languages (e.g., od-IN for Odia).
Diagnosis: Check if the language code is in the supported list:
en-IN, hi-IN, bn-IN, ta-IN, te-IN, mr-IN, gu-IN, kn-IN, ml-IN, pa-IN, sd-IN
Fix: Use a supported BCP-47 language code, or omit language entirely to let Gemini auto-detect from the text script.
3. Invalid Voice + Language Combination
Symptoms: 500 with a valid language but specific voice.
Diagnosis: Not all Gemini voices support all languages. Current supported voices: Kore, Orus, Leda, Charon.
Fix: Try a different voice (default: Kore) or test the combination in Google AI Studio.
4. Deprecated or Renamed Model
Symptoms: 500 across all requests regardless of language/voice.
Diagnosis: Gemini TTS models are in preview and may be renamed or rotated. Current known models:
gemini-2.5-pro-preview-ttsgemini-2.5-flash-preview-tts
Fix: Verify model availability at [Gemini model docs](https://ai.google.dev/gemini-api/docs/models/gemini) and update SUPPORTED_MODELS in app/models/llm/request.py.
Quick Triage Checklist
| Step | Action | Pass? |
|---|---|---|
| 1 | Update google-genai SDK to latest |
☐ |
| 2 | Test with model=gemini-2.5-flash-preview-tts, voice=Kore, language=en-IN |
☐ |
| 3 | If step 2 works, narrow down by changing one param at a time | ☐ |
| 4 | If step 2 fails, check [Google AI Status](https://status.cloud.google.com/) for outages | ☐ |
| 5 | Test directly in [Google AI Studio](https://aistudio.google.com/) to isolate SDK vs API issue | ☐ |
Key Files
| Purpose | Path |
|---|---|
| TTS provider | app/services/llm/providers/gai.py → _execute_tts |
| Language map | app/services/llm/mappers.py → BCP47_LOCALE_TO_GEMINI_LANG |
| Defaults & models | app/models/llm/request.py → DEFAULT_TTS_MODEL, SUPPORTED_MODELS |
Relevant sources google/adk-python#1113