Written by Oğuzhan Karahan
Last updated on Jul 17, 2026
●15 min read
Gemini 3.5 Flash Thought Signature Error: Fix 400 Errors
A 400 on Gemini tool calling often looks like a model failure.
In practice, it is usually a missing or mangled thought signature in your history path.
This guide shows what to preserve, what to echo, and how to stop Gemini multi-turn tool calling from breaking.
Tool chains fail after the first call.
Your multi-turn agent looks healthy until function results go back and Gemini returns a 400. Approvals stall while retries burn time on a stack that still looks correct.
That wasted effort usually tracks the history path, not the model.
The catch:
A Gemini 3.5 Flash thought signature error is usually conversation-state mismanagement, not downtime. Thought signatures are encrypted reasoning tokens that must return intact to preserve multi-turn and multi-step context.
The better move:
Diagnose the history path before you rewrite the agent. The practical outcome is a clear state handoff across capture, echo, parallel tool-call consistency, full-response history, and intermediary audits.
Custom mappers, OpenAI-compatible routers, and hand-built histories are where most stacks fail. Fix the handoff, and multi-turn tool calling stops breaking for the same reason.
What Thought Signatures Preserve Across Tool Turns
Thought signatures are encrypted reasoning-state tokens that Gemini returns so multi-turn and multi-step tool context stays intact. Gemini 3 models enforce stricter signature validation than earlier versions. If a required signature is missing on a later request, the API returns a 400 error instead of continuing the agent loop.
They appear on model response parts that include a functionCall, carried as a thought_signature field.
Treat that field as required provider state, not optional debug metadata.
Without it, the model loses encrypted reasoning continuity when the next tool turn starts.
Gemini 3 models enforce this more strictly than previous Gemini versions because it improves function-calling performance.
So when you build the next request, include the functionCall part and its thought_signature exactly as the model returned them.
Even MINIMAL thinking levels still require that return when the documentation says a signature is required.
Thought blocks can also hold only a signature with no summary. Your history store still needs the signature field intact.
Why a Gemini 3.5 Flash Thought Signature Error Appears
A Gemini 3.5 Flash thought signature error is usually history and state mismanagement, not model downtime. Missing, invalid, reordered, or intermediary-dropped signatures cause Gemini API 400 INVALID_ARGUMENT failures during tool calling. The break appears when prior model response state is not echoed correctly.
The failure rarely hits on the first isolated user prompt.
It shows up after tools run, when you rebuild history for the next model turn.
Gemini needs the encrypted reasoning state from prior model responses returned on later requests.
If your stack drops that field, reorders parts, or rebuilds only text and tool names, validation fails.
Community-reported Gemini API 400 error patterns often mention a missing thought_signature on a functionCall part.
Other community-reported messages surface a Gemini thought signature not valid style failure.
Both point to incomplete or corrupted conversation state, not a generic outage.
The common failure surfaces include dropped provider metadata, wrong part placement, and incomplete history reconstruction.
A Gemini function calling error often appears mid-loop even when tool execution itself succeeded.
The model path looks healthy. The history path is not.
That means the 400 is a state handoff bug in your conversation builder, proxy, or mapper.
Do not treat it as proof the model is down until you verify the signature-bearing parts still exist in the request.
Gemini Multi-Turn Tool Calling: Echo Rules That Prevent 400s
During Gemini multi-turn tool calling, return every required thought_signature from prior model responses on later requests. Include each functionCall part exactly as returned, then append tool results. Missing required signatures, even at MINIMAL thinking, produce a 400 instead of continuing the agent loop.
The turn model is capture, execute, then echo.
You store model response parts that carry functionCall and thought_signature, run the tools, and send function results with those original parts still intact.
That echo rule is what keeps Gemini multi-turn tool calling valid across steps.
Hand-built histories fail when they keep tool names and text but drop signature fields before the next request.
Capture the Model Parts Before You Send Tool Results
Store the full model steps before you execute any tool.
Do not keep only the function name and arguments.
Capture functionCall parts and thought_signature exactly as returned.
Run the tool with those arguments.
Append the function_result or functionResponse to history.
Resubmit the full history with signature fields intact.
Exact-as-returned part handling is the rule.
If you strip signature fields before the next request, validation fails even when tool execution succeeded.
Sequential Steps Still Need Signature Continuity
Sequential multi-step function calling validates every step in the current turn.
Omit a required thought_signature for the first functionCall part in any step of that turn, and the API returns a 400.
A turn begins with the most recent user message that is not a functionResponse.
Signature continuity must hold for every step inside that boundary, not only the first tool hop.
Gemini Parallel Tool Calls and Signature Consistency
When Gemini returns multiple function calls in one response, keep signature handling consistent across every functionCall part that requires a thought_signature. Return those parts exactly as the model produced them. Dropping one required signature can trigger a 400 and may degrade tool performance.
Gemini parallel tool calls add a multi-part consistency rule.
When several functionCall parts arrive together, each required thought_signature must stay attached.
You cannot keep some tool calls and drop signature metadata from others.
Partial rebuilds create avoidable 400 failures on the next request.
Do Not Partially Serialize Multi-Call Model Messages
Rebuild the full multi-functionCall model message without selective metadata drops.
Keep every required signature-bearing functionCall part intact and exactly as returned.
Keep all functionCall parts from the same model response.
Keep each thought_signature field exactly as returned.
Do not serialize only tool names and arguments.
Do not drop provider metadata while keeping tool structure.
Partial serialization is a common Gemini function calling error path.
It breaks validation on the follow-up request.
Missing One Signature Can Invalidate the Whole Follow-Up
One missing required signature on a parallel part can block the entire follow-up request.
Gemini 3 models return a 400 INVALID_ARGUMENT style failure when a required thought_signature is missing.
Community-reported patterns often cite a function call missing a thought_signature in functionCall parts.
Those patterns also warn that missing thought_signature may lead to degraded model performance.
Treat the failure as multi-part history integrity, not a permanent product guarantee.
When the Official SDK Handles Thought Signatures for You
When you use the official Google Gen AI SDK with standard chat history or append full model responses, thought signatures are handled automatically. Automatic function calling also manages them transparently. Prefer full-response append over hand-built partial histories to keep reasoning state intact.
This is the low-friction path for multi-turn agents.
If your stack can stay on official chat history helpers, stop rebuilding model turns by hand.
Official guidance is direct. Use the official SDKs and standard chat history, and thought signatures are handled for you.
Google Gen AI notebook guidance matches that rule. When you append model content correctly, there is no extra signature work.
The thought_signature travels back inside the model turn content. Automatic function calling handles that field transparently as well.
The better move: append the full model response, then attach tool results, then continue.
Do not rebuild only tool names, arguments, and text. That is where signature-bearing parts disappear.
Function-calling examples for gemini-3.5-flash follow the same pattern. Capture model steps, then resubmit full history on the next turn.
Official thinking docs also note that the Interactions API makes thought-signature handling simpler than manual reconstruction. That still assumes you preserve complete model steps across turns.
Treat third-party SDKs as separate systems. Do not assume they match official auto-handling unless their docs say so.
Use the official path when you can. Save custom history logic for cases where the SDK cannot own the conversation state.
Manual History, Proxies, and Signature Drop Points
Manual history builders, OpenAI-compatible proxies, and custom mappers often drop, reorder, or misplace thought signatures. That produces Gemini thought signature not valid failures and related 400s. The model is usually fine. Your transport or history normalization path is not.
Most Gemini function calling error reports after the first tool round point here.
You kept the tool names and arguments. You lost the provider metadata Gemini needs on the next turn.
Official SDK chat history hides that risk. Custom mappers surface it.
Stripping Provider Metadata During History Normalization
Custom history builders often keep text, tool names, and arguments while dropping thought_signature.
That is a primary failure mode.
Normalized message schemas look clean for storage. They break Gemini multi-turn tool calling because later turns no longer carry encrypted reasoning state.
If your mapper flattens provider metadata into a generic chat schema, restore signature-bearing model parts before the next request.
Wrong Part Placement and Invalid Signature Reattachment
Thought signatures must stay on the functionCall-bearing parts the model returned.
Wrong part placement invalidates the follow-up even when the signature string still exists somewhere in history.
Reordering parts or reattaching a signature to a text part is another common break.
Community-reported patterns include 400 Invalid Argument style failures when thought_signature is attached to text parts instead of the expected function-call structure. Do not invent or forge a replacement value.
OpenAI-Compatible Routers That Lose Google-Specific Fields
OpenAI-compatible routers, proxies, and third-party agent stacks often do not preserve Google-specific signature fields across tool rounds.
The practical result is Gemini thought signature not valid responses, or missing-signature 400s, on later turns.
Community-reported integration symptoms match this path: the intermediary response exposes tool names and arguments, but no signature field survives into your history mapper.
Audit the transport layer before blaming the model. If the proxy cannot echo Google-specific fields, route tool turns through a path that preserves full model parts.
Streaming and Request Paths That Change Signature Handling
Streaming does not remove thought-signature requirements. Capture complete model steps from the stream before the next tool turn. Official docs note the Interactions API simplifies signature handling versus lower-level paths, while continuity still depends on returning required signature-bearing parts.
Streaming with thinking is supported in official Gemini docs.
A thought block may stream with only a signature and no summary.
Handle empty or absent summaries without dropping signature fields.
Assemble full model steps from the completed stream before you append function results.
Do not continue with partial tool-call fragments and missing provider metadata.
Official docs describe the Interactions API as making thought signature handling much simpler than manual lower-level wiring.
GenerateContent multi-turn examples still capture model steps and resubmit full history with function results.
Release notes note the Interactions API already errors on mismatched function responses, while GenerateContent does not yet.
That difference covers response matching, not a rewrite of signature continuity rules.
Even in streaming, later turns need signature-bearing parts from the completed model response.
If your stream aggregator keeps only tool names and arguments, you recreate the same Gemini API 400 error path.
Fix Checklist for Thought Signature 400 Failures
Fix a Gemini API 400 from missing thought signatures by capturing raw model response parts, echoing signatures on later turns, preferring official SDK full-response history append, auditing intermediaries for field loss, keeping parallel tool-call parts consistent, and retesting multi-turn tool calling after each change.
Treat every 400 as a state-transport problem first. Isolate whether the break is local history, parallel serialization, or an intermediary.
Work the list in order. Stop when the next tool turn succeeds.
Capture raw model response parts from the failed turn, including every functionCall part and its thought_signature exactly as returned.
Echo those signature-bearing parts on the next request with function results attached. Do not rebuild only tool names and arguments.
Prefer full-response history append through the official Google Gen AI SDK or standard chat history when possible.
Audit intermediaries if local history looks correct: proxies, OpenAI-compatible routers, and custom mappers that strip provider metadata.
Keep every required signature-bearing functionCall part intact for parallel tool calls.
Retest Gemini multi-turn tool calling after each change so you know which step restored continuity.
Do not forge signatures or invent random base64 values. Community reports show that path fails with invalid-signature errors and is not an official fix.
If a Gemini API 400 error remains after capture and echo, the transport layer is usually dropping Google-specific fields between turns.
A Gemini 3.5 Flash thought signature error that clears after full-response append is a history bug, not a model outage.
Limitations When Signature Handling Still Breaks
Even with correct echo rules, signature handling still has hard limits. Gemini 3 validation is stricter than older models. Custom stacks and intermediaries still need explicit preservation. Thinking-level settings never remove required signature returns. Community edge cases can change and are not product guarantees.
Official docs state Gemini 3 models enforce stricter thought-signature validation than previous versions because it improves function-calling performance.
That stricter gate is why small history mistakes now surface as 400s.
Custom history builders still need explicit preservation of signature-bearing parts.
The official SDK auto-path only helps when you use standard chat history or append full model responses.
Intermediaries such as proxies and OpenAI-compatible routers may still drop Google-specific fields.
Those layers may need updates before multi-turn tool workflows stay stable.
Setting thinking_level to minimal or low does not cancel the return requirement.
If docs require a thought_signature on a functionCall part, you must still send it back.
A Gemini 3.5 Flash thought signature error still points to conversation-state mismanagement, not a universal model outage.
When signature handling still breaks after checklist fixes, audit preservation first. Do not treat remaining failures as proof the model is down.
Frequently Asked Questions
Can I forge or invent a thought_signature to bypass a Gemini API 400 error?
No. Return the exact signature-bearing model parts the API already produced. Community-reported attempts with random base64 or invented values fail with invalid-signature style 400s, and official guidance is exact echo, not forgery.
Is a missing thought_signature the same as Gemini thought signature not valid?
They are related symptoms with different failure modes. Missing usually means the field was dropped before the next turn. Not valid often means the value was corrupted, reordered, misplaced on the wrong part, or mangled by an intermediary.
Does setting thinking_level to minimal remove thought signature requirements?
No. Minimal or low thinking does not cancel required returns. If documentation requires a thought_signature on a functionCall part, you must still echo it on later tool turns for Gemini multi-turn tool calling.
Why do OpenAI-compatible routers break Gemini multi-turn tool calling?
Many OpenAI-style schemas keep tool names and arguments but drop Google-specific fields such as thought_signature. Later turns then fail with a Gemini function calling error or thought signature not valid style 400 even when tool execution already succeeded.
If the official Google Gen AI SDK auto-handles signatures, why do framework agents still fail?
Auto-handling works when you use standard chat history or append full model responses. Frameworks that rebuild partial histories, normalize provider metadata away, or route through proxies reintroduce drop points and recreate the same Gemini 3.5 Flash thought signature error path.
What should I inspect first when debugging a Gemini 3.5 Flash thought signature error?
Compare the raw model response parts to the next request payload. Confirm every required functionCall part still carries thought_signature, part order is unchanged, and no proxy stripped provider metadata. Then retest with official full-response history append before blaming the model.
Does the Interactions API let me ignore thought signatures completely?
No. Official docs say Interactions simplifies signature handling versus lower-level wiring, but continuity still depends on preserving complete model steps across turns. Streaming and Interactions do not remove the need to keep signature-bearing parts intact for Gemini parallel tool calls and later tool rounds.
