Repository navigation
Deprecated model alias (gemini-flash-latest) causes confusing 404 NOT_FOUND with no actionable guidance #6010
Description
Summary
When deploying an ADK application to Cloud Run (or any environment where a deprecated Gemini model alias is configured), all LlmAgent calls silently fail with a confusing 404 NOT_FOUND error that does not clearly indicate the root cause.
Environment
google-adk: 2.1.0google-genai: latest- Platform: Google Cloud Run (asia-northeast1)
- Python: 3.12
Steps to Reproduce
- Set
GEMINI_MODEL=gemini-flash-latestin the environment (common in older ADK projects or tutorials that referenced this alias) - Pass it to
LlmAgent:MODEL = os.environ.get("GEMINI_MODEL", "gemini-flash-latest") agent = LlmAgent(name="MyAgent", model=MODEL, ...)
- Deploy to Cloud Run and invoke the agent
Actual Error
google.genai.errors.ClientError: 404 NOT_FOUND.
{'error': {'code': 404, 'message': 'This model models/gemini-2.0-flash is
no longer available. Please update your code to use a newer model for the
latest features and improvements.', 'status': 'NOT_FOUND'}}
Problem
The error message mentions models/gemini-2.0-flash — the resolved underlying model ID — but the user configured gemini-flash-latest. This disconnect makes diagnosis difficult:
- The user sees
gemini-2.0-flashin the error but never wrote that name anywhere - There is no hint that
gemini-flash-latestis the problematic alias - The error surface is deep in the agent invocation chain, far from the configuration
This was particularly confusing during a hackathon where the app appeared to work locally (older cached responses / different routing) but failed 100% on Cloud Run.
Root Cause
gemini-flash-latest is a non-versioned alias that previously resolved to gemini-2.0-flash. Google has since deprecated gemini-2.0-flash (the specific model behind the alias), causing the alias to produce 404 errors.
Note: ADK 2.1.0 correctly uses DEFAULT_MODEL = 'gemini-2.5-flash' — the issue occurs when users explicitly pass an old alias via environment variable or hardcoded string.
Suggested Improvements
Option A — Startup validation warning
Before agent invocation, validate the model string against a known deprecated-alias list and emit a logging.warning:
DeprecationWarning: model alias 'gemini-flash-latest' is no longer available.
Please use 'gemini-2.5-flash' or a versioned model ID.
Option B — Improved error interception
Catch 404 NOT_FOUND errors from the Gemini API and re-raise with a user-friendly message:
ModelDeprecatedError: The model alias 'gemini-flash-latest' resolved to
'gemini-2.0-flash' which has been deprecated. Please update your model
configuration to 'gemini-2.5-flash'.
Option C — Documentation
Add a "Model Version Management" section to the ADK docs / README warning users against non-versioned aliases and recommending pinned model IDs.
Workaround
Replace any occurrence of gemini-flash-latest (or other non-versioned aliases) with a specific versioned model ID:
# Before (breaks silently when alias is deprecated)
MODEL = os.environ.get("GEMINI_MODEL", "gemini-flash-latest")
# After (stable, explicit)
MODEL = os.environ.get("GEMINI_MODEL", "gemini-2.5-flash")This was discovered while building a multi-agent privacy tool (AI Shield Persona Agent) for the ADK Hackathon. Sharing in case it helps other hackathon participants and ADK users.
Activity
surajksharma07 commentedon Jun 8, 2026
/adk-issue-analyze
adk-bot commentedon Jun 8, 2026
I have completed a thorough analysis and triage of GitHub Issue #6010 regarding the confusing runtime crashes caused by deprecated Gemini model aliases.
The complete triaging report has been written to the local artifact directory:
👉 analysis_results.md
Executive Summary
Configuring non-versioned legacy aliases like
'gemini-flash-latest'fails during agent execution with a confusinggoogle.genai.errors.ClientError: 404 NOT_FOUNDreferencing'models/gemini-2.0-flash'. Since developers did not directly configure'gemini-2.0-flash', finding the source of the deprecation error is difficult.Yes, Pull Request #6011 is currently
OPEN. It was submitted by@he-yufengon2026-06-08. It adds an early warning lookup table to help developers transition.Should Fix (Medium Priority). The proposed fix in PR fix: warn on deprecated Gemini model alias #6011 is precise, safe, aligns perfectly with the codebase guidelines, and alerts developers during startup validation instead of intercepting remote errors.
Root Cause & Code Locations
gemini-flash-latest.404client error.For additional information on the analysis and PR details, please see the full analysis_results.md report. Please let me know if you would
surajksharma07 commentedon Jun 8, 2026
@pj0201 The gemini-flash-latest alias quietly resolves to gemini-2.0-flash on the backend, which Google has deprecated — that's why the 404 references a model name you never actually configured.
As a quick workaround, try swapping to gemini-2.5-flash directly (either via GEMINI_MODEL=gemini-2.5-flash or in your agent definition) and verify whether that clears the error on Cloud Run.
If it does, the proper fix is adding a startup warning in LLMRegistry.new_llm() for known deprecated aliases — PR #6011 is already open and covers exactly this case.
Please do a full test run before raising anything further, and let us know how the swap goes!
pj0201 commentedon Jun 9, 2026
@surajksharma07 Thanks for the guidance!
We actually upgraded to
gemini-3.5-flash(GA since May 2026) instead of 2.5, ran the app, and confirmed the 404 errors are gone — PII detection working correctly on Cloud Run.Looking forward to PR #6011 being merged!
surajksharma07 commentedon Jun 11, 2026
@pj0201 Great — that confirms it: any versioned model ID clears the 404, since the failure was gemini-flash-latest resolving to the retired gemini-2.0-flash behind the scenes.
Went through #6011 as well — the deprecated-alias table in LLMRegistry.new_llm() fires after prefix parsing, so both gemini-flash-latest and gemini:gemini-flash-latest forms get the warning while the model string still passes through unchanged.
It sits on the exact path LlmAgent.canonical_model uses, so the coverage is correct.
The PR is in review with the team now and will close this issue when it lands.
One note worth dropping on the PR thread rather than a blocker: the warning only covers string-configured models (a Gemini(model=...) instance bypasses the registry), and the alias table is worth growing with the other -latest aliases over time.
Team is looking more into it.
Thanks!
GWeale commentedon Jun 16, 2026
Thanks for the detailed report! After looking into this, we've decided not to add alias-deprecation detection in ADK.
The backend already returns a 404 naming the resolved model as no longer available, which is the authoritative signal. The fix on the app side is to use a pinned, versioned model ID (e.g. gemini-2.5-flash) instead of a non-versioned alias.
Closing as working as intended
fix(ai): basculer vers la génération Gemini 3.x (gemini-3.1-flash-lite)