Gemini Tool Call History Corruption

[zain]

Summary

When using @convex-dev/agent with Google's Gemini models (@ai-sdk/google), tool call history can become corrupted in a way that causes subsequent requests to fail with Gemini's strict function call ordering validation. The error only manifests when Gemini attempts to output a new function call, making it intermittent and difficult to diagnose.

Environment

• @convex-dev/agent: ^0.3.2
• ai (Vercel AI SDK): ^5.0.113
• @ai-sdk/google: (latest compatible)
• Model: gemini-3-flash-preview (also likely affects other Gemini models)

Error Message

Error: Please ensure that function call turn comes immediately after a user turn or after a function response turn.

AI_APICallError
statusCode: 400
url: https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:streamGenerateContent

Reproduction Steps

1. Create an agent with tools using Gemini:

const chatAgent = new Agent(components.agent, {
  name: "Assistant",
  languageModel: google("gemini-3-flash-preview"),
  tools: {
    myTool: createTool({
      description: "Does something",
      args: z.object({ input: z.string() }),
      handler: async (ctx, args) => ({ success: true }),
    }),
  },
  maxSteps: 5,
});

2. Send a message that triggers a tool call:

const result = await chatAgent.streamText(
  ctx,
  { threadId },
  { model: google("gemini-3-flash-preview"), prompt: "Do the thing" },
  { saveStreamDeltas: true }
);
await result.consumeStream();

3. Tool call succeeds, tasks/data created correctly

4. Send another message that might trigger a tool call:

// This fails with the Gemini validation error
const result2 = await chatAgent.streamText(
  ctx,
  { threadId },
  { model: google("gemini-3-flash-preview"), prompt: "Do another thing" },
  { saveStreamDeltas: true }
);

5. Intermittent failure: If Gemini decides to call a tool, validation fails. If Gemini just outputs text, it succeeds.

Root Cause Analysis

Gemini's Strict Requirements

Gemini requires this exact message sequence for function calls:

user → model(functionCall) → user(functionResponse) → model(text)

Key constraints:

• functionCall must come immediately after a user turn or functionResponse
• functionResponse has role: "user" in Gemini's format (not role: "tool")
• Cannot have model(functionCall) → model(text) without the functionResponse in between

Suspected Issues in @convex-dev/agent

1. filterOutOrphanedToolMessages May Drop Valid Tool Results

In client/search.js:

export function filterOutOrphanedToolMessages(docs) {
  const toolCallIds = new Set();
  const toolResultIds = new Set();

  // Collect IDs...

  // Filter tool results to only those with matching toolCallIds
  else if (doc.message?.role === "tool") {
    const content = doc.message.content.filter((c) => toolCallIds.has(c.toolCallId));
    if (content.length) {
      result.push({...});
    }
    // If no match, message is SILENTLY DROPPED
  }
}

If toolCallId doesn't match exactly (due to serialization, encoding, or race conditions), the tool result is dropped, leaving:

user → model(functionCall) → model(text)

This is invalid and causes Gemini to reject new function calls.

2. serializeNewMessagesInStep May Miss Messages

In mapping.js:

const hasToolMessage = step.response.messages.at(-1)?.role === "tool";
const messages = hasToolMessage
  ? step.response.messages.slice(-2)  // Only last 2 messages
  : step.response.messages.slice(-1); // Only last message

If step.response.messages contains more than 2 messages (e.g., [assistant(tool_call), tool(result), assistant(text)]), only the last 1-2 are saved, potentially losing the tool_call or tool_result.

3. docsToModelMessages Filter

In mapping.js:

export function docsToModelMessages(messages) {
  return messages
    .map((m) => m.message)
    .filter((m) => !!m)
    .filter((m) => !!m.content.length)  // Could filter valid messages
    .map(toModelMessage);
}

If a tool message has empty content after filterOutOrphanedToolMessages processing, it gets dropped here.

Evidence from Production Logs

12/20/2025, 6:33:35 AM [CONVEX A(chatActions:streamResponse)] Function executed in 20679 ms  // SUCCESS with tool call
12/20/2025, 6:48:35 AM [CONVEX M(chat:sendMessage)] Function executed in 137 ms
12/20/2025, 6:48:39 AM [CONVEX A(chatActions:streamResponse)] [ERROR] 'onError' {
  error: Error: Please ensure that function call turn comes immediately after a user turn...
  statusCode: 400,
}
12/20/2025, 8:02:56 AM [CONVEX A(chatActions:streamResponse)] Function executed in 7236 ms  // SUCCESS (no tool call)

Note: The 8:02 request succeeded because Gemini responded with text only (no tool call validation triggered).

Suggested Fixes

Option A: Fix filterOutOrphanedToolMessages

Add logging when messages are dropped:

else if (doc.message?.role === "tool") {
  const content = doc.message.content.filter((c) => toolCallIds.has(c.toolCallId));
  if (content.length) {
    result.push({...});
  } else {
    console.warn('Dropping orphaned tool message:', doc._id,
      'toolCallIds in message:', doc.message.content.map(c => c.toolCallId),
      'available toolCallIds:', [...toolCallIds]);
  }
}

Option B: Fix serializeNewMessagesInStep

Save ALL messages from the step, not just the last 1-2:

const messages = step.response.messages.filter(m =>
  m.role === "assistant" || m.role === "tool"
);

Option C: Add Gemini-Specific Validation

Before sending to Gemini, validate the conversation structure:

function validateGeminiHistory(messages) {
  let expectingFunctionResponse = false;
  for (const msg of messages) {
    if (msg.role === "model" && hasFunctionCall(msg)) {
      expectingFunctionResponse = true;
    } else if (msg.role === "user" && hasFunctionResponse(msg)) {
      expectingFunctionResponse = false;
    } else if (expectingFunctionResponse && msg.role === "model") {
      throw new Error("Missing functionResponse after functionCall");
    }
  }
}

Workaround

Until fixed, users can add error handling with context truncation:

try {
  await chatAgent.streamText(...);
} catch (error) {
  if (error.message?.includes("function call turn")) {
    // Retry with tool messages filtered out
    await chatAgent.streamText(ctx, { threadId }, {
      ...args,
      contextOptions: {
        excludeToolMessages: true,
      }
    });
  }
}

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• OpenAI with search tool - failing save in validator #125

Related Issues

• Tool return value requirements and TypeScript errors #103
• Duplicate messages with stuck streaming state after tool approval (saveStreamDeltas) #185
• Tool validation - Uncaught Error: InvalidToolInputError #142
• Handling long running agents #199

👤 Suggested Assignees

• eliotgevers
• christiannwamba
• TGNC
• jedimonkey
• wantpinow

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[ianmacartney]

Sorry for the delay zain! I saw this but realized I never actually replied. A few thoughts:

The error seems to be about the function call turn following a user or function response turn, but the reproduction steps seems to have step (3) creating a function call and response, and the call in (4) should be a user message, so I'm not sure why it would fail, or why the failure would be about the final resulting tool call vs. text, instead of something intermediate.

Suspected issues responses:

1. If there isn't a matching toolCallId, that seems like a bigger problem - I don't buy the "serialization, encoding, or race conditions" rationale there. If anything, it is likely not filtering out enough messages - you mentioned the tool result is a role of user, not tool - but that code assumes the role is "tool". If users are submitting tool responses, we should drop those if there isn't a corresponding tool call.

2. The AI SDK code (linked from that source) only adds one or two messages. If that has changed, we need to figure it out, but I suspect it hasn't.

3. If the assistant message made tool calls but none of them have valid responses, then the assistant message should be safe to drop - the previous message should already be a user or function response, based on the gemini rules, so I don't see a way that removing the message with no valid calls would result in an invalid chain.

Production logs are helpful - can you dump the messages in the thread earlier than that timestamp when you see it? Seeing the exact sequence of messages that are failing would help.

Option responses:

A: You can already compare the messages at that time with the messages being used - you could log in a custom contextHandler, and can look at the data in the dashboard too.

B: The response.messages I believe can include messages from previous steps, when doing multi-step generation, whereas for each step we only want to save the most recent one(s)

C: This logic would likely be happily homed in the filterOurOrphanedToolMessages. And you can already put this in the contextHandler if you want to validate.

My suspicion is that the problem is coming from the role being "user" for gemini tool responses. I wonder whether AI SDK is already handling this for gemini and we could still store them as "tool". Having tool responses be "user" messes with a few things:

1. For user messages we often increment order instead of just incrementing stepOrder. When using promptMessageId, e.g. we only fetch tool responses on the same "order" as the original prompt.

2. We split up UIMessages by user message boundaries, assuming that we'll see a tool role for tool responses.

3. Our DeltaStreamer implementation assumes stepOrder is incremented for each step, and will likely try to save the message at the end with the calculated stepOrder, which might conflict with the user message saving calculation.

Knowing what the list of bad messages are would help a ton here.