Gemini 2.5 Pro and 2.5 Flash Retire on December 1: The Migration Checklist

Google announced on November 2 that gemini-2.5-pro and gemini-2.5-flash are deprecated, with a shutdown date of December 1, 2026. The important part is not the date. It is what happens on that date: requests do not start failing. They start succeeding against a different model, at that model's rates.

That is the trap. A service that suddenly errors is easy to notice. A service that keeps returning answers while quietly running on gemini-3.8-flash or gemini-3.5-flash-lite is not, especially if your logs record the model you asked for rather than the model that answered. "No errors" is not evidence that nothing changed.

The practical deadline is therefore before December 1: change the model string, change the parameters, and run a regression on the paths that matter.

What the deprecation actually says

Both models are deprecated and no longer selectable in Google AI Studio. API access is limited to existing users who have actively used them in the past, so a new key cannot simply pick them up for a comparison test.

The deprecation page and the release notes both state that effective December 1, 2026, all API requests to the old names will automatically route to their replacements and be billed at the replacement models' rates. Google's guidance is to update the model string before that date.

Two consequences follow. First, the old names keep working after the deadline, which removes the forcing function that usually drives migrations. Second, cost and behavior both change without a deploy on your side. If you have a budget alert tied to a fixed per-call assumption, it will drift.

There is a testing implication too. Because the old models are no longer offered to new selections, a side-by-side comparison may not be available on a fresh key or project. If you want a before-and-after baseline, capture it while your existing access still works, and store the outputs rather than relying on memory of how the old model behaved.

The replacement mapping is a tier change

The official mapping is short:

• gemini-2.5-pro routes to gemini-3.8-flash
• gemini-2.5-flash routes to gemini-3.5-flash-lite

Read those pairs carefully. The first moves a Pro-tier model onto a Flash-tier model. The second moves a Flash model onto a Flash-Lite model. These are not like-for-like substitutions, and the migration guide for the 3.8 family documents a set of API changes that go with the move.

That matters for evaluation. A prompt suite tuned to the old model's instruction-following, refusal behavior, or tool-calling style is not automatically a valid test of the replacement. Treat the swap as a model change with a new baseline, not as a version bump.

The breaking changes to plan for

The Gemini 3.8 migration guide lists the concrete API differences. Five of them affect real integrations.

Thinking configuration becomes an enum. thinking_budget is replaced by the string enum thinking_level. On Gemini 3.8 Flash, minimal is not supported; the valid choices are low, medium (the default), and high. Code that computed a numeric budget now needs a mapping decision, and that decision is a quality and latency trade-off rather than a mechanical translation.

Sampling parameters are removed. temperature, top_p, and top_k are no longer accepted. This is the change most likely to surface as a hard error on the first request, and the one most likely to have been tuned over months. If your prompts depended on a low temperature for determinism, that control is gone and has to be replaced by prompt and schema discipline.

candidate_count is unsupported. It does not work on Gemini 3 and later. Workflows that generated several candidates and picked one need to move that selection logic outside the request.

Prefilled model turns are removed. Multi-turn conversations should be standardized on the server-side previous_interaction_id. Prefill was often used to force an output format; the replacement is a schema or instruction, not a half-written assistant turn.

Function calling needs an audit. The guide calls out several details: place multimodal assets inside the response payload, format inline instructions with \n\n, check Malformed_Function_Call errors tied to pre-tool text, and, if you use the generateContent API, ensure every FunctionResponse includes call_id and name. It also points to thought_signature preservation, which is easy to break when an SDK is upgraded casually.

Signatures deserve separate attention because they fail quietly. They are what lets the model verify that a tool result belongs to the call it issued. If an SDK upgrade drops them, or if a proxy strips fields it does not recognize, requests may still succeed while tool loops behave oddly. Treat "we upgraded the SDK" as a change that requires the same regression as a model swap.

The checks matter because the failure is rarely a clean exception. A tool call with a missing field, or a signature that no longer matches, can still return a response; it just returns the wrong one more often than before.

A five-step order that avoids rework

1. Find every model string. Search configuration files, environment variables, SDK client construction, job definitions, notebooks, and fallback defaults. The old names are often in more than one place, and the one you miss is usually the one in the nightly job.

2. Change the name and run in a test environment. Do not combine the name change with parameter changes in a single deploy if you can avoid it. You want to know which change caused a difference in output.

3. Change the parameters. Replace thinking_budget with thinking_level and choose low, medium, or high deliberately. Remove temperature, top_p, top_k, and candidate_count. Remove prefilled model turns and move multi-turn state to previous_interaction_id.

4. Run a regression, not a smoke test. Compare outputs on the prompts that represent real traffic, with attention to function calling and multi-turn flows. The testing approach for model and prompt changes is the right frame: fixed evaluation inputs, recorded outputs, and a review of differences rather than a pass or fail on one example.

5. Check billing and latency after rollout. The new model is billed at its own rates, and the thinking-level choice moves latency. The usage and cost tracking guide covers the instrumentation side; the point here is to look at the new baseline rather than assume the old one carries over.

The quiet failure mode: hardcoded fallbacks

The most expensive version of this migration is the one that appears to be done. A client often has a fallback path: if the configured model is unavailable, use a hardcoded default. When the old name starts auto-routing, that fallback may still be pointing at the retired model, and the request succeeds anyway.

The result is a system that reports no errors, serves traffic, and is not running the model you think it is. If logs record only the requested model, the discrepancy is invisible.

Two habits close this gap. Grep for the old model names in every layer, including defaults buried in client wrappers. And record the model that actually served the response, not just the one you requested, following the field discipline in the logging guide. The same discipline makes cost attribution possible after the switch.

Two shutdown styles, two failure modes

It helps to compare this with the OpenAI deprecation covered earlier this month. There, requests to a retired model fail; the migration is enforced by errors, and the model string must change. The replacement table and the exact failure behavior are in the October shutdown analysis.

Gemini's approach is the opposite: keep the name working, route it to a successor, and bill at the successor's rates. Nothing breaks at the boundary. The breakage, if any, is behavioral and financial, and it arrives quietly.

Neither style is inherently better. But they demand different monitoring. Error-rate dashboards catch the first. Only model-identity logging and output regression catch the second.

For the general method, including how to inventory dependencies and stage a migration, the deprecation migration playbook covers the parts that are the same regardless of vendor.

Checklist

1. Search the entire codebase and configuration for gemini-2.5-pro and gemini-2.5-flash, including fallback defaults.
2. Decide the replacement per workload: gemini-3.8-flash for the Pro model, gemini-3.5-flash-lite for the Flash model.
3. Replace thinking_budget with thinking_level, choosing low, medium, or high; do not use minimal on Gemini 3.8 Flash.
4. Remove temperature, top_p, top_k, and candidate_count from affected requests.
5. Remove prefilled model turns and standardize multi-turn state on previous_interaction_id.
6. Audit function calling: response payloads, \n\n formatting, Malformed_Function_Call, and call_id plus name on every FunctionResponse for generateContent.
7. Run a regression on real prompts, with separate attention to tool calls and multi-turn flows, before December 1.
8. After rollout, verify the model that actually served traffic and re-baseline cost and latency.

The date is not the risk. The risk is a migration that looks finished because nothing threw an error.

Model names and API behavior above follow the official pages as checked on 2026-11-03; confirm them against the current documentation before changing production configuration.