Bug: no Gemini model in providers.json is usable on a new API key (2.5-flash / 2.5-flash-lite return 404 "no longer available to new users")

[ayo0la]

Problem

None of the five Gemini models shipped in providers.json completes a request on a newly created free-tier API key. Two of them fail with a hard 404 model-availability error that no amount of quota or billing will fix — and they are exactly the two models .env.example recommends.

Evidence

Probed each shipped model against the same endpoint OpenAICompatibleProvider uses (POST https://generativelanguage.googleapis.com/v1beta/openai/chat/completions, Authorization: Bearer <key>), with a key created today:

model	status	message
gemini-2.0-flash	429	You exceeded your current quota...
gemini-2.0-flash-lite	429	You exceeded your current quota...
gemini-2.5-flash	404	This model models/gemini-2.5-flash is no longer available to new users. Please update your code to use a newer model...
gemini-2.5-flash-lite	404	This model models/gemini-2.5-flash-lite is no longer available to new users...
gemini-2.5-pro	429	You exceeded your current quota...

The 404s are the unambiguous bug: gemini-2.5-flash and gemini-2.5-flash-lite are retired for new users at the model level, independent of quota or billing.

I want to be precise about the 429s rather than overclaim: I cannot fully separate "free-tier requests-per-day is 0 for these models" from ordinary quota exhaustion on my project, since I had spent quota on this key earlier the same day. They are reported here as observed, not as proven config bugs. The 404s stand on their own.

Models that do return 200 on the same key and endpoint, none of which are in providers.json:

• gemini-flash-latest
• gemini-flash-lite-latest
• gemini-3.1-flash-lite

Repro

cp .env.example .env
# set GEMINI_API_KEY to a newly created key
DEFAULT_MODEL=gemini-2.5-flash python score.py ./resume/sample.pdf --role software_engineering_intern

Fails on the first section-extraction call with the 404 above. config.provider_for() resolves fine — the model is in providers.json, so the failure surfaces only at request time.

Why this bites new contributors specifically

.env.example:3 recommends "gemini-2.5-pro" and "gemini-2.5-flash", and README.md:189 uses gemini-2.5-pro as its worked example. A new contributor following the README verbatim with a fresh key hits a hard failure on their first run, with an error that reads like their key is broken rather than the config being stale.

Suggested fix

Replace the retired pins with the -latest aliases, which do not go stale as individual model versions are retired:

• gemini-flash-latest
• gemini-flash-lite-latest

Keeping a dated pin alongside them is fine, but the aliases are what stop this recurring — the same class of breakage will hit gemini-3.x pins in a few months. Doc references in .env.example and README.md need updating to match.

Happy to open a PR for this if it is not already in flight.