top of page

Gemini API empty response with finishReason MAX_TOKENS: why thinking uses up the token limit

2 minutes ago
8 min read
Gemini API empty response with finishReason MAX_TOKENS cover with the Gemini logo, Data Studios original cover

Last verified: November 18, 2026


A Gemini API call returns HTTP 200, the usage numbers show that the model worked, and yet the text you print is empty or stops in the middle of a sentence. When the candidate carries the finish reason MAX_TOKENS, Google's own documentation explains what happened: the model spent the output budget on its hidden reasoning before it wrote the answer. Raise maxOutputTokens or lower the thinking level, and the missing text comes back in most cases.


The problem affects every model that thinks by default, which today means the Gemini 4 family, Gemini 3.x Flash and Pro, and Gemini 2.5 Pro and Flash. It shows up most often after a move from an older model to a thinking one, when an application keeps an output limit sized for visible text only. Reports on Google's developer forum go back to the Gemini 2.5 previews in May 2025 and continue on Gemini 3.8 Flash in September 2026, and the official thinking guide, last updated on October 14, 2026, still describes the behavior as expected.


··········


THE GEMINI API "MAX_TOKENS" EMPTY OUTPUT AND WHERE YOU SEE IT.


The failure does not arrive as an error. The request succeeds, the response contains a candidate, and the only signals are in fields that many applications never log. In the generateContent API the candidate's finishReason reads MAX_TOKENS, which the API reference defines as "the maximum number of tokens as specified in the request was reached". The text part is an empty string, contains only whitespace, or is missing entirely, while usageMetadata reports a large thoughtsTokenCount and a candidatesTokenCount that is null or very small.


Forum reports show the pattern clearly. One developer on gemini-2.5-flash had max_output_tokens set to 3,072 and received 3,071 reasoning tokens and zero output tokens. Another on a Gemini 2.5 Pro preview logged 1,023 thought tokens and no candidate tokens at all. In the Python SDK this surfaces as response.text being empty, and frameworks built on top of it, such as LangChain integrations, pass the empty string to your application as if it were a valid answer.


The newer Interactions API reports the same event with different names. There the limit is max_output_tokens, the thought count is total_thought_tokens inside interaction.usage, and Google's thinking guide says that a model which hits the limit while reasoning "stops generating with status "incomplete" and returns truncated or empty output".


........


Interface

Limit field

Thought-token field

Signal when thinking used the limit

generateContent (REST)

generationConfig.maxOutputTokens

usageMetadata.thoughtsTokenCount

finishReason MAX_TOKENS, empty or cut text

Google GenAI SDK for Python

max_output_tokens

usage_metadata.thoughts_token_count

finish_reason MAX_TOKENS, empty response.text

Interactions API

generation_config.max_output_tokens

usage.total_thought_tokens

status incomplete, empty or cut output

Long decode on Gemini 4 Argon

max_output_tokens (all hops)

per hop usage

CONTINUATION with empty text is normal progress


........


··········


WHY GEMINI THINKING TOKENS CONSUME THE OUTPUT LIMIT.


Thinking models reason in a private step before they write the reply. Google's thinking guide states that the output limit "sets the maximum number of tokens a response can generate, including thought tokens", so reasoning and answer draw from one shared budget. If the model is still reasoning when the budget runs out, there is nothing left for the visible answer, and the guide says the call ends "with finish_reason: MAX_TOKENS and returns truncated or empty output".


The cost side follows the same rule. The guide says that "response pricing is the sum of output tokens and thinking tokens", and it adds that thinking tokens are still billed when the limit cuts the response short. An empty MAX_TOKENS response is therefore a paid response, which is one reason to fix it in configuration instead of retrying the same request in a loop.


Default reasoning depth makes the problem easy to trigger. The thinking guide lists medium as the default level for Gemini 4 Carbon, Gemini 4 Argon and Gemini 3.8 Flash, high for Gemini 4 Hydrogen, Gemini 3.1 Pro Preview and the Gemini 3 previews, and minimal for the Gemini 3 Flash-Lite models. A prompt that asks for careful analysis of a long document can easily spend several thousand thought tokens at medium or high, which is more than a limit of 1,024 or 2,048 tokens copied from a summarization script written for an older model.


··········


CAUSES OF EMPTY GEMINI API RESPONSES, HOW TO CHECK AND THE FIX.


Several different situations end with an empty string in your code. Reading three fields (finishReason, thoughtsTokenCount and promptFeedback) separates them in a few seconds.


........


Cause

How to check

Fix

Thinking used the whole output limit

finishReason MAX_TOKENS, thoughtsTokenCount close to maxOutputTokens, candidate tokens null or tiny

Raise maxOutputTokens or lower thinkingLevel

Limit too small for the answer itself

finishReason MAX_TOKENS, text present but cut mid-sentence

Raise the limit, ask for a shorter answer, or continue the request

Long decode hop spent on thinking

finishReason CONTINUATION, a continuation_token, empty text

Resend with the token until the finish reason changes

Prompt blocked before generation

promptFeedback.blockReason is set, no candidates returned

Read the block reason and rephrase the prompt

Candidate stopped by a filter

finishReason SAFETY, RECITATION, PROHIBITED_CONTENT or similar

Check safetyRatings and change the request

Empty reply with finishReason STOP

STOP with no parts, often in tool-calling or grounded flows

No documented cause; see the reported workarounds below


........


The first two rows are the documented MAX_TOKENS cases and account for most reports. The last row looks similar in logs but carries a different finish reason, and Google has not published an explanation for it.


··········


STEP-BY-STEP FIXES FOR GEMINI MAX_TOKENS WITH EMPTY TEXT.


1. Log the full response before reading the text. Record finishReason for each candidate, the whole usageMetadata object and promptFeedback. Without these fields every empty answer looks the same, and the wrong fix is likely.


2. Compare thoughtsTokenCount with your limit. If the thought count equals or nearly equals maxOutputTokens and candidatesTokenCount is null, thinking consumed the budget. Raise maxOutputTokens with enough room for both the reasoning and the expected answer. Google's long decode page gives the per-request defaults for Gemini 4 Argon: 64K output tokens for streaming calls and for non-streaming calls made through the Google GenAI SDK, and 32K for direct non-streaming REST calls to generateContent, where a value above 32,768 without a continuation token returns a 400 error.


3. Lower the thinking level when the task does not need deep reasoning. For Gemini 4 and Gemini 3 models the control is thinkingLevel, which the thinking guide calls required for Gemini 4 and recommended for Gemini 3. Gemini 4 models and Gemini 3.8 Flash accept low, medium and high (Gemini 4 Hydrogen also accepts xhigh), while minimal exists only on some Gemini 3 Flash and Flash-Lite models. Google's guide recommends this route over a very small output limit when the goal is lower cost or latency.


4. Use thinkingBudget only on Gemini 2.5. The thinkingBudget parameter belongs to the 2.5 series and is deprecated for Gemini 4. On 2.5 Flash the budget runs from 0 to 24,576 and a value of 0 turns thinking off; 2.5 Pro accepts 128 to 32,768 and cannot turn thinking off. Never send thinkingBudget and thinkingLevel in the same request, because the guide says that combination returns a 400 error.


5. Handle truncated text separately from empty text. If the answer is present but cut short, either raise the limit, ask the model for a more compact format, or, on Gemini 4 Argon, use the continuation mechanism described on the long decode page: resend the same request with the continuation_token and a higher max_output_tokens, which must exceed the tokens already used.


6. Treat CONTINUATION as progress. With long decode, a hop can spend all its tokens on thinking and return empty text together with a continuation_token. Google's page treats this as normal. Keep sending the latest token while the finish reason is CONTINUATION, do not add the partial output to contents, and join the parts from all hops into one model turn. The latest Google GenAI SDK does this automatically when max_output_tokens exceeds the per-request cap.


7. Check for blocks before retrying. If promptFeedback.blockReason is present, the API reference says no candidates are returned and the prompt should be rephrased; for SAFETY it points to safetyRatings to see which category blocked it. Retrying the same blocked prompt only repeats the result.


The configuration below is taken from Google's thinking guide for the Python SDK and shows how to set a lower thinking level and print the two token counts that diagnose the problem:


from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Provide a list of 3 famous physicists and their key contributions",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)

print(response.text)
print("Thoughts tokens:", response.usage_metadata.thoughts_token_count)
print("Output tokens:", response.usage_metadata.candidates_token_count)

In REST the same setting goes inside generationConfig as "thinkingConfig": {"thinkingLevel": "low"}, next to maxOutputTokens.


··········


WHAT GOOGLE DOCUMENTS AND WHAT GEMINI DEVELOPERS ONLY REPORT.


The official pages settle the main mechanism. The thinking guide for generateContent and the guide for the Interactions API both state that thought tokens count toward the output limit, that reaching the limit during reasoning returns truncated or empty output, and that thinking tokens are billed. The long decode page, updated on October 13, 2026, confirms that the limit covers thinking and output for all hops together.


Other observations come only from developers on Google's forum, and none of them has an official answer.


........


Observation

Where reported

Status

Totals near twice maxOutputTokens, with the excess always in thought tokens

One developer, Gemini 3.8 Flash and 3.7 Flash, September 2026

Unconfirmed, no staff reply

finishReason STOP with no parts, often with function calls or Search grounding

Many users, Gemini 2.5 and Gemini 3 previews, up to April 2026

No documented cause

Setting thinking level to medium instead of the default high ended empty replies

One user, Gemini 3 Pro Preview, google-genai 1.61.0, February 2026

User report

Raising the limit to very high values did not help in some 2025 cases

Users on Gemini 2.5 Flash previews

A forum moderator said it was resolved in June 2025; later reports continued


........


The overshoot report has a direct effect on budgeting. In five test runs on Gemini 3.8 Flash with a limit of 512 tokens and low thinking, the developer logged totals between 997 and 1,003 tokens, and in production a 16,384-token limit produced totals up to 32,108. Google has not commented, so applications that cap spend through maxOutputTokens alone should treat the documented limit as a target and monitor the actual thoughtsTokenCount.


The STOP-with-empty-parts reports describe a different failure. Workarounds shared by users include an explicit thinking level, a short instruction inside the functionResponse, and adding the URL context tool to grounded requests, with mixed results. Retries helped some developers and failed for others.


··········


PREVENTING EMPTY GEMINI RESPONSES AFTER A MODEL CHANGE.


Most cases start with a model switch. When an application moves to a Gemini 4 model, Gemini 3.8 Flash or any other model that thinks by default, the old maxOutputTokens value should be reviewed, because it now has to cover hidden reasoning too. Our reference on OpenAI, Claude and Gemini token-limit parameters lists how each provider names and counts this limit, and the list of current Gemini, Claude and DeepSeek model names helps confirm which model an alias resolves to.


Three habits catch the problem before users see it. Alert on any candidate whose finishReason is not STOP, and on any STOP response with empty text. Store thoughtsTokenCount next to candidatesTokenCount for each call, so a jump in reasoning after a model update is visible in dashboards. Set the thinking level explicitly in code instead of relying on model defaults, which differ across the Gemini 4, Gemini 3 and Flash-Lite families.


Empty responses also interact with timeouts and capacity errors. Higher thinking levels lengthen each request, and a busy model can then return 503 errors or exceed a short client timeout, as described in our page on the Gemini API 503 high-demand error.


··········


GEMINI API MAX_TOKENS AND THINKING: THE CONCLUSIONS FOR DEVELOPERS.


An empty Gemini response with finishReason MAX_TOKENS is documented behavior: the shared output budget ran out during reasoning, and the thought tokens were billed anyway. The reliable fixes are a larger maxOutputTokens, a lower thinkingLevel on Gemini 4 and Gemini 3, or a thinkingBudget on Gemini 2.5, never both thinking controls in one request.


Two adjacent cases need their own handling. CONTINUATION with empty text on Gemini 4 Argon is normal long decode progress and needs the continuation token, while STOP with empty parts has no official explanation and only community workarounds. Logging finishReason, thoughtsTokenCount and promptFeedback on every call is the cheapest way to tell these cases apart, and it also reveals the reported overshoot above the configured limit on Gemini 3.8 Flash if it affects your workload.


··········


FOLLOW US FOR MORE.


·····


DATA STUDIOS


·····


datastudios.org


bottom of page