`FINISH_REASON_MAX_TOKENS` — Gemini on Vertex AI stopped at the output cap

finishReason: FINISH_REASON_MAX_TOKENS

If you pasted that value into a search box, a Gemini call on Google Cloud stopped writing before it had finished, and your agent may have taken the partial text as the answer. Here is what Google’s own references say the value means, read off them today, and the checks that tell you which number to change.

What the vendor says it means

The model inference reference, at docs.cloud.google.com/gemini-enterprise-agent-platform/reference/models/inference, lists it under finishReason, which it describes as “The reason why the model stopped generating tokens.”:

FINISH_REASON_MAX_TOKENS: The maximum number of tokens as specified in the request was reached.

The Gemini API reference, at ai.google.dev/api/generate-content, gives the same stop the same sentence under a shorter name:

MAX_TOKENS: The maximum number of tokens as specified in the request was reached.

So the two spellings carry one meaning, and the fix below is the same for both. Notice what the value is not. The call did not fail. It returned, and it reported why generation stopped: it ran into a token ceiling, not into the end of what the model had to say.

Which ceiling “the request” means

The field is maxOutputTokens. The Vertex reference describes it as “Maximum number of tokens that can be generated in the response. A token is approximately four characters. 100 tokens correspond to roughly 60-80 words.” By that ratio a cap of 256 tokens is roughly 150 to 200 words, which is short for an agent step that writes code or a plan.

If you never set it, a limit still applied. The Gemini API reference describes maxOutputTokens as “The maximum number of tokens to include in a response candidate” and adds: “Note: The default value varies by model, see the Model.output_token_limit attribute of the Model returned from the getModel function.” So when your code sends no cap, the number that stopped you belongs to the model, and you find it in the model’s metadata, not in your code.

Two more lines matter for agents.

Streaming. The Vertex reference says of finishReason: “If empty, the model has not stopped generating the tokens.” In a stream, the turn is not over until a chunk carries a non-empty value. Read the value off that chunk before you decide the turn is done.
Thinking. The Vertex reference says of thinkingBudget: “By default, the model automatically controls how much it thinks up to a maximum of 8,192 tokens.” The Gemini API reference reports thinking separately in the usage block, as thoughtsTokenCount, “Number of tokens of thoughts for thinking models”, and defines totalTokenCount as “(prompt + thoughts + response candidates)”. On a truncated response, read thoughtsTokenCount next to candidatesTokenCount before you touch the cap. It shows how much of the turn went to thinking and how much to the answer.

How this differs from the pages next door

Claude’s stop_reason: max_tokens is another vendor’s field with its own rules; it has its own page. Within Gemini, some strings can come back from either of two enums, and another page covers those. This one cannot: the Gemini API reference lists BlockReason as BLOCK_REASON_UNSPECIFIED, SAFETY, OTHER, BLOCKLIST, PROHIBITED_CONTENT and IMAGE_SAFETY, and MAX_TOKENS is not among them. It is never a blocked prompt. It is always a candidate that ran out of room.

The fix

Branch on the enum, not on the text. Treat FINISH_REASON_MAX_TOKENS and MAX_TOKENS alike as “incomplete”, and accept both spellings. Do not pass the text to the next step as a finished answer.
Do not parse a cut-off structured answer. If you asked for JSON through responseMimeType or responseSchema, both in the request body the reference documents, an object cut off at the cap can fail to parse, or parse into something incomplete, a few steps later. Check the finish reason before the parser runs.
Find out which number you hit. Compare candidatesTokenCount, “Number of tokens in the response(s)” in the Vertex reference, with the maxOutputTokens you sent. If you sent none, look up the model’s output_token_limit.
Then pick the lever. If the answer needs the room, raise maxOutputTokens. If thoughtsTokenCount is a large share of the turn, thinkingLevel is the documented control, “Controls the amount of internal reasoning the model performs before generating a response.” If neither fits, ask for less in each call.

A raised cap fixes the call in front of you. The agent that hits it again next week is the one whose steps keep growing. The lasting fix is to make each step small enough that the cap is never the thing that ends it, and to make the loop check the finish reason on every turn.

What is behind this site

There is a written guide: the step-and-turn arithmetic as a formula you can run against a brief before you launch it, why raising a cap does not finish the job, and batch.py, one standard-library file that collapses a per-item loop into a single pass. It is $19, on a Gumroad storefront. One working way to pay today is 19 USDC on Base: you email the transaction hash and the guide is delivered by email. This page is free, ungated, and sells nothing on its own.

The short version: FINISH_REASON_MAX_TOKENS, or MAX_TOKENS on the Gemini API, means “The maximum number of tokens as specified in the request was reached.” The ceiling is maxOutputTokens, and if you never set it, the model’s default applied. It is never a blocked prompt. Treat the turn as incomplete, compare candidatesTokenCount and thoughtsTokenCount with the cap, then raise the cap, lower the thinking level, or ask for less per call.

Nearby

stop_reason: max_tokens — the Claude version: a truncated response on an HTTP 200, and why the cap may not be yours.
blockReason vs finishReason — the five Gemini values that belong to both enums.
finishReason: SAFETY, RECITATION, OTHER — the Gemini stop values whose docs define themselves.
finishReason: length — the same stop as the Vercel AI SDK reports it, with the provider’s word in rawFinishReason.

This page counts anonymous readership with one counter, the file at /measure.js, and each of the events below is sent at most once per load. Once the page is ready it sends one view event. With it go the page path, the domain of the page you came from — only the domain, and nothing at all if you came from this site — how long the page has been open, counting only the time it was actually in front of you and not the time it sat in a background tab, whether you have scrolled, and any campaign or outreach code in the link you followed. A second event, which we call a human candidate, is sent only once the page has also received a real input event from you — a mouse movement, a touch, a scroll or a key press — and has been visible in the foreground for ten seconds in all; a program that fetches the page, or opens it and sits there, cannot produce one. A third, “engaged”, is stricter still: it is sent only after the human-candidate event, once the page has been in front of you for ninety seconds in all and you have scrolled far enough to reach a marker we put where the explaining part of this page ends; a reader who stops short of that marker never produces one. The second and third events carry the same fields as the first. If you switch away from the tab or close it, an event that has just become due may be sent as you leave. If this page has a button or a copy control that says it records a click, pressing it sends the name of that event and nothing else. Following a link to buy the guide sends one further event, also at most once per load, carrying that event’s name and a single word for which of the two checkouts you were sent to — the Gumroad listing or the payment page on this site — and nothing else: not the address you followed, not which page you were reading, not how long you had been there. Everything is sent to this site only, with no cookie attached. No cookie is read or written, nothing is put in your browser’s local or session storage, and no identifier is made from your device. Earlier versions of this page kept the campaign codes of your first visit in local storage under the name llab_attr; this page neither reads nor deletes that entry, so if it is there it stays until you clear this site’s data. An outreach code is minted per recipient, which would let us tell one reader from another; it is sent with each event and, unlike on earlier versions of this page, it is no longer removed from the address bar after it is read — if you copy the address, the code goes with it. Earlier versions also asked this domain for Vercel’s analytics script at /_vercel/insights/script.js, which on 26 September 2026 returned HTTP 404 on every host we publish; this page no longer asks for it. Your browser and the network attach things the page does not send: the identification string your browser gives, your IP address and the time of the request. The host that serves this page keeps its own request logs; those are its record and not ours.

FINISH_REASON_MAX_TOKENS — Gemini on Vertex AI stopped at the output cap