Deprecated model alias (gemini-flash-latest) causes confusing 404 NOT_FOUND with no actionable guidance

[pj0201]

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.0
• google-genai: latest
• Platform: Google Cloud Run (asia-northeast1)
• Python: 3.12

Steps to Reproduce

1. Set GEMINI_MODEL=gemini-flash-latest in the environment (common in older ADK projects or tutorials that referenced this alias)
2. Pass it to LlmAgent:

   MODEL = os.environ.get("GEMINI_MODEL", "gemini-flash-latest")
   agent = LlmAgent(name="MyAgent", model=MODEL, ...)

3. 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-flash in the error but never wrote that name anywhere
• There is no hint that gemini-flash-latest is 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.

[surajksharma07]

/adk-issue-analyze

[adk-bot]

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

1. What is broken?
   Configuring non-versioned legacy aliases like 'gemini-flash-latest' fails during agent execution with a confusing google.genai.errors.ClientError: 404 NOT_FOUND referencing 'models/gemini-2.0-flash'. Since developers did not directly configure 'gemini-2.0-flash', finding the source of the deprecation error is difficult.
2. Is there a linked PR that fixes this issue?
   Yes, Pull Request #6011 is currently OPEN. It was submitted by @he-yufeng on 2026-06-08. It adds an early warning lookup table to help developers transition.
3. Recommendation:
   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

• Validation Gap: LLMRegistry.new_llm parses the configured model string but lacks a checklist to warn about deprecated model designations like gemini-flash-latest.
• Model Resolution: LlmAgent.canonical_model resolves the model string to an active model subclass instance.
• Runtime Invocation: Gemini.generate_content_async makes the backend API call which receives the downstream 404 client 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]

@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!