If Gemini API returns empty response text with finishReason set to MAX_TOKENS, do not treat the request as a complete answer merely because the HTTP request completed. Inspect candidate metadata, token usage, model configuration, and the installed SDK version.
Google defines MAX_TOKENS as a finish reason indicating generation reached the output-token limit configured for the request. The response schema exposes candidate content and usage metadata to help distinguish a truncated answer from a response that has no text for another reason.
Official references: Gemini API troubleshooting and GenerateContent response fields.
Quick checklist
- Inspect the raw response, not only a convenience text property.
- Read the candidate finish reason and content parts.
- Check prompt, output, and thinking-token usage where exposed.
- Verify generation configuration field names for your installed SDK.
- Confirm the model supports the requested settings and output limit.
- Handle absent or empty content explicitly in your application.
Read the finish reason
The finish reason is diagnostic evidence. MAX_TOKENS points toward the configured token ceiling; SAFETY, RECITATION, BLOCKLIST, and other reasons require a different diagnosis. Check whether the candidate exists and whether its content contains text parts. Some SDK convenience properties may return no value or raise an error when text is absent.
Check the output-token configuration
Review the maximum output-token setting in the request and compare it with the selected model’s documented limits. Do not copy a limit from another model and assume it applies universally. A small output budget can produce incomplete results for long tasks. Increase it only within the supported maximum and your cost and latency constraints.
If the prompt is large, reduce redundant context or divide the task into stages rather than increasing limits blindly. For reasoning models, inspect usage metadata where available because internal thinking tokens can contribute to total consumption.
Verify SDK configuration names
A frequent integration issue is using a configuration property from an older SDK version after upgrading. Compare your code with the current official example for the exact SDK and version installed. Check the lockfile and the package version in the production environment; it may differ from local development.
Do not rename a parameter based only on a forum post. Verify the current SDK documentation for the installed version and API interface.
Distinguish other empty responses
If the finish reason is MAX_TOKENS, investigate token settings first. If it is STOP but no content exists, the token limit alone does not explain the result. Inspect all candidates and metadata, check whether tools or grounding were used, and run a minimal reproduction with a short prompt and supported model.
If the minimal request works but the complex one fails, compare prompt size, tools, response schema, and model settings one at a time. If minimal requests also fail intermittently, consult Google’s troubleshooting guidance and service status before assuming the cause is your code.
Add defensive handling
Before using generated text, check that a candidate and content exist and that at least one text part contains usable text. If the response is truncated, request a shorter answer, split the task, or use a supported continuation approach. Do not retry the same oversized request indefinitely; retries can add cost without changing the token ceiling.
Log the model, finish reason, relevant configuration, and usage metadata, but avoid storing private prompts or credentials.
MAX_TOKENS does not prove that every empty response has the same cause. Invalid parameters, unsupported model settings, safety filtering, tool behavior, SDK mismatches, and transient service issues need separate checks.
Official sources: Gemini API troubleshooting and GenerateContent response schema.
Related troubleshooting
For broader AI troubleshooting, start with the exact error and the official documentation for the product involved. This article focuses on the specific API or publishing failure described above, rather than general introductory guidance.