Gemini NOT_FOUND: meaning, cause, and fix

Cause one: the file you referenced is gone

Google's troubleshooting docs give one official cause for the 404: the request referenced a file that isn't there. That covers media you attach by reference instead of inline, meaning images, audio, and video. Uploaded references don't live forever; they can expire or get deleted, and nothing pings you when one quietly vanishes. Your code keeps presenting a handle to a resource that stopped existing somewhere between the upload and this call.

For an unavailable file reference, upload the file again, capture the new reference, and resend. Long-running jobs should treat file handles as temporary: catch the 404, refresh the reference, and continue as the snippet below shows. If a fresh upload does not resolve the error, confirm that the request parameters match the selected API version; a version mismatch can produce a similar debugging path.

Cause two: the model retired

The second cause is bigger than your request: the entire model line has been switched off. Three verified dates matter as of June 2026. gemini-3-pro-preview has been dead since March 9, 2026. The gemini-2.0-flash family shut down June 1, 2026. And gemini-2.5-pro plus gemini-2.5-flash carry an October 16, 2026 date, which Google publishes as the earliest possible shutdown rather than a promise of extra time. The 2.5 Pro deprecation record and the model tracker keep the full timeline.

Migration has a price tag, literally. On the Pro path, gemini-3.1-pro-preview replaces 2.5 Pro, and $1.25/$10 becomes $2/$12 for Gemini 3.1 Pro. On the Flash path, benchr's editorial pick as of September 2026 is gemini-3.8-flash, the current Flash. Gemini 3.8 Flash bills $0.75 input / $3.75 output per 1M tokens through December 31, 2026, against $0.30/$2.50 on Gemini 2.5 Flash, and rises to $1.50/$7.50 on January 1, 2027. Gemini 3.5 Flash, which this page pointed to in June, costs $1.50/$9, more than 3.8 Flash on both sides. A one-line config change can multiply a bill, so budget for the 2027 rate before you ship the swap.

The response

Here's a representative 404 body, in Google's standard error shape:

{
  "error": {
    "code": 404,
    "message": "The requested resource wasn't found.",
    "status": "NOT_FOUND"
  }
}

Branch on the status field; NOT_FOUND stays stable while message wording can drift. Notice what the body never tells you: which of the two causes you've hit. The calendar usually does. A 404 that starts on the morning of a published shutdown date is a retirement, not a file glitch.

The fix in code

For the file case, wrap the call so a stale reference triggers one re-upload and one retry instead of a crash loop:

# Python (google-genai): re-upload when a file reference 404s
from google import genai
from google.genai import errors

client = genai.Client()

def ask_about(path, prompt, model="gemini-3.8-flash"):
    ref = client.files.upload(file=path)
    try:
        return client.models.generate_content(model=model, contents=[ref, prompt])
    except errors.APIError as e:
        if e.code != 404:
            raise
        ref = client.files.upload(file=path)   # stale handle: refresh it
        return client.models.generate_content(model=model, contents=[ref, prompt])

For the retirement case, the entire code change is one line of config:

# config.yaml
-  model: gemini-2.5-flash
+  model: gemini-3.8-flash

One step remains before re-pointing production traffic: re-quote the bill. At Gemini 3.8 Flash's 2026 rate that diff raises input cost 2.5-fold at list price, and five-fold from January 1, 2027. A jump that's tolerable for a chatbot can wreck a batch pipeline. Check current numbers in the Gemini 3.8 Flash review, push your own token volumes through the calculator, and ship the migration with the budget already signed off.