client.files.upload() fails with KeyError: 'file' when uploading .jsonl (Batch API)

TL;DR

The SDK does not check the upload response for errors, so that backend 400 surfaces as a confusing KeyError: 'file' instead of the real error.

KeyError: 'file'

When to use

You are seeing this: 1. [dget, orhansonmeztr, alexerhardt, prathapbelli (reporters)]: The docs example passed mime_type='jsonl', which the backend rejects with 'Unsupported MIME type: application/jsonl'. Use this skill when you run into "client.files.upload() fails with KeyError: 'file' when uploading .jsonl (Batch API)".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Steps

1. [dget, orhansonmeztr, alexerhardt, prathapbelli (reporters)]: The docs example passed mimetype='jsonl', which the backend rejects with 'Unsupported MIME type: application/jsonl'. The SDK does not check the upload response for errors, so that backend 400 surfaces as a confusing KeyError: 'file' instead of the real error. Workaround confirmed by several reporters on the thread: upload the .jsonl file with mimetype='application/json'. If you hit a bare KeyError after files.upload, print the raw response first, the real API error is hiding behind it.

Why this happens

This happens when using the example code from the docs verbatim.

In gh:googleapis/python-genai#1590 (Google Gemini), the issue reported was: Issue googleapis/python-genai#1590 (closed, 28 comments): Hi team, thank you for the great Gemini SDK! I just wanted to report that the JSONL upload example from the official Batch API docs currently fails with a KeyError: 'file' when using client.files.upload(). When following the official Gemini Batch API documentation, uploading a .jsonl file via client.files.upload() fails with KeyError: 'file'. This happens when using the example code from the docs verbatim. The API call succeeds (HTTP 200), but the SDK throws a KeyError because the JSON response The verified resolution from the thread: [dget, orhansonmeztr, alexerhardt, prathapbelli (reporters)]: The docs example passed mimetype='jsonl', which the backend rejects with 'Unsupported MIME type: application/jsonl'. The SDK does not check the upload response for errors, so that backend 400 surfaces as a confusing KeyError: 'file' instead of the real error. Workaround confirmed by several reporters on the thread: upload the .jsonl file with mimetype='application/json'. If you hit a bare KeyError after files.upload, print the raw response first, the real API error is hiding behind it. Source: mount the host path https at container path //github.com/googleapis/python-genai/issues/1590