AI_InvalidPromptError ("messages must be a ModelMessage[]") caused by undefined properties in tool-result arrays

[wladimiiir]

Description

I am encountering an AI_InvalidPromptError when using the tool helper. The top-level error message suggests a mismatch between UI/Model messages, but the underlying cause is a schema validation failure (AI_TypeValidationError) on the tool result.

My tool returns an array of objects where some properties are optional (string | undefined). When the tool executes, some objects have these properties set to undefined, causing the keys to be stripped during JSON serialization. The SDK's internal validation for the tool-result message then fails, seemingly expecting a uniform shape across all items in the array or failing to handle the missing keys that were typed as optional.

Reproduction:

1. Define a tool that returns an array of objects.
2. Ensure the return type infers specific fields as string | undefined.
3. Return an array where some items have the field defined, and others have it as undefined.
4. Trigger the tool via generateText or streamText.

Code Snippet:

import { tool } from 'ai';
import { z } from 'zod';

// Tool Definition
const listTasksTool = tool({
  description: 'List tasks',
  inputSchema: z.object({
    limit: z.number().optional(),
  }),
  // No explicit outputSchema provided, relying on inference
  execute: async ({ limit = 20 }) => {
    // Simulating database response where 'startedAt' is optional
    const tasks = [
      {
        id: "1",
        state: "completed",
        startedAt: "2025-10-26T17:59:40.065Z", // Field exists
        completedAt: "2025-10-26T18:00:31.713Z"
      },
      {
        id: "2",
        state: "archived",
        startedAt: undefined, // Field is undefined (will be stripped in JSON)
        completedAt: undefined 
      }
    ];

    return tasks; 
  },
});

// Inferred Return Type confirms optionality:
// Tool<..., { id: string; startedAt: string | undefined; ... }[]>

The Issue:
The resulting tool-result message passed to the messages array looks like this (keys are missing for the second item):

{
  "role": "tool",
  "content": [
    {
      "type": "tool-result",
      "toolName": "tasks---list_tasks",
      "output": {
        "type": "json",
        "value": [
          { "id": "1", "startedAt": "2025-10-26..." },
          { "id": "2" } // "startedAt" is missing entirely here
        ]
      }
    }
  ]
}

Error Log:
The application crashes with the following error:

AI_InvalidPromptError: Invalid prompt: The messages must be a ModelMessage[]. If you have passed a UIMessage[], you can use convertToModelMessages to convert them.

Upon inspecting the cause, it reveals an AI_TypeValidationError (Zod validation failure) on the missing keys in the array:

{
  "name": "AI_TypeValidationError",
  "cause": [
    {
      "code": "invalid_union",
      "errors": [
        // ... validation path showing failure on index 1 of output.value ...
        {
          "code": "invalid_type",
          "expected": "string",
          "message": "Invalid input: expected string, received undefined",
          "path": ["startedAt"]
        }
      ]
    }
  ]
}

Expected Behavior:
The SDK should handle tool-result payloads where keys are missing if the value was undefined, or the generic inference should be lenient enough to accept heterogeneous arrays in output.value without requiring an explicit outputSchema that forces null. The error message regarding ModelMessage[] vs UIMessage[] is also confusing in this context as the messages are structurally correct aside from the tool payload validation.

AI SDK Version

• ai: 5.0.106

Code of Conduct

• I agree to follow this project's Code of Conduct

[shubham-021]

@wladimiiir hey , i tried reproducing this issue :

import { openai } from "@ai-sdk/openai";
import { generateText, stepCountIs, tool } from "ai";
import { z } from "zod";
import 'dotenv/config';

const listTasks = tool({
    description: 'List tasks',
    inputSchema: z.object({
        limit: z.number().optional()
    }),
    execute: ({limit = 20}) => ([
        {
            id: "1",
            state: "completed",
            startedAt: "2025-10-26T17:59:40.065Z",
            completedAt: "2025-10-26T18:00:31.713Z"
        },
        {
            id: "2",
            state: "archived",
            startedAt: undefined,
            completedAt: undefined 
        }
    ])
})

const model = openai('gpt-4o-mini');

const printResult = async () => {
    const result = await generateText({
        model,
        prompt: 'List all the tasks',
        tools: {
            listTasks
        },
        stopWhen: stepCountIs(5),
        maxRetries: 3,
        system: 'You are an helpful assistant'
    });

    // console.log(result.text)
    console.log(JSON.stringify(result,null,2));
}

printResult().catch(console.error);

But it doesn't throw any type of validation error , rather it executes successfully and provides me the list.

{
  "role": "tool",
  "content": [
    {
      "type": "tool-result",
      "toolCallId": "call_N3rhmBdllGj2S0i7QDfbBv5G",
      "toolName": "listTasks",
      "output": {
        "type": "json",
        "value": [
          {
            "id": "1",
            "state": "completed",
            "startedAt": "2025-10-26T17:59:40.065Z",
            "completedAt": "2025-10-26T18:00:31.713Z"
          },
          {
            "id": "2",
            "state": "archived"
          }
        ]
      }
    }
  ]
}

And the final text response:

Here are the tasks:

1. **Task ID:** 1
   - **State:** Completed
   - **Started At:** October 26, 2025, 17:59:40
   - **Completed At:** October 26, 2025, 18:00:31

2. **Task ID:** 2
   - **State:** Archived

Are you using any different provider ?

[wladimiiir]

@shubham-021
Hm, interesting. I have tried it with multiple providers - google, openai-compatible, openrouter...

I am not using the stopWhen: stepCountIs(5), as I need to do some additional processing in between each iteration, so each subsequent iteration calls streamText with newly added messages, so maybe that's what's different.

Just to note, when I return the values as null it works fine.

    execute: ({limit = 20}) => ([
        {
            id: "1",
            state: "completed",
            startedAt: "2025-10-26T17:59:40.065Z",
            completedAt: "2025-10-26T18:00:31.713Z"
        },
        {
            id: "2",
            state: "archived",
            startedAt: null,
            completedAt: null 
        }
    ])

Can you maybe try to omit the startedAt, completedAt to see if you can reproduce it?

    execute: ({limit = 20}) => ([
        {
            id: "1",
            state: "completed",
            startedAt: "2025-10-26T17:59:40.065Z",
            completedAt: "2025-10-26T18:00:31.713Z"
        },
        {
            id: "2",
            state: "archived",
        }
    ])

Thank you.

[shubham-021]

@wladimiiir you were right , i tried it by manually iterating over the steps and i was able to reproduce the issue.

import { openai } from "@ai-sdk/openai";
import { streamText, tool } from "ai";
import { z } from "zod";
import 'dotenv/config';

const listTasks = tool({
    description: 'List tasks',
    inputSchema: z.object({
        limit: z.number().optional()
    }),
    execute: ({limit = 20}) => ([
        {
            id: "1",
            state: "completed",
            startedAt: "2025-10-26T17:59:40.065Z",
            completedAt: "2025-10-26T18:00:31.713Z"
        },
        {
            id: "2",
            state: "archived",
            startedAt: undefined,
            completedAt: undefined
        }
    ])
})

const model = openai('gpt-4o-mini');

const reproduce = async () => {
    const result1 = streamText({
        model,
        messages:[
            { role: 'user', content: 'List all the tasks' }
        ],
        tools: { listTasks }
    });

    for await (const chunk of result1.textStream) {}
    
    const response1 = await result1.response;
    
    const result2 = streamText({
        model,
        messages:[
            { role: 'user', content: 'List all the tasks' },
            ...response1.messages
        ],
        tools: { listTasks }
    });
    
    for await (const chunk of result2.textStream) {
        process.stdout.write(chunk);
    }
};
reproduce().catch(console.error);

1388 |   const validationResult = await safeValidateTypes({
1389 |     value: messages,
1390 |     schema: z6.array(modelMessageSchema)
1391 |   });
1392 |   if (!validationResult.success) {
1393 |     throw new InvalidPromptError2({
                     ^
AI_InvalidPromptError: Invalid prompt: The messages must be a ModelMessage[]. If you have passed a UIMessage[], you can use convertToModelMessages to convert them.

Let me go through this once , so i can find the cause.

[shubham-021]

@wladimiiir
When using stopWhen: stepCountIs(), validation happens only once during the initial call. Subsequent steps bypass validation, which is why it doesn't throw errors even when tool results have heterogeneous arrays.

However, when manually iterating each call triggers validation again, causing the error.

The Problem:

execute: ({limit = 20}) => ([
    {
        id: "1",
        state: "completed",
        startedAt: "2025-10-26T17:59:40.065Z",
        completedAt: "2025-10-26T18:00:31.713Z"
    },
    {
        id: "2",
        state: "archived",
        startedAt: undefined,
        completedAt: undefined
    }
])

infered type:

Array<{
    id: string;
    state: string;
    startedAt: string | undefined;  // Key must exist
    completedAt: string | undefined; // Key must exist
}>

When this is JSON serialized , undefined values are stripped:

[
    {"id": "1", "state": "completed", "startedAt": "2025-10-26T17:59:40.065Z", "completedAt": "2025-10-26T18:00:31.713Z"},
    {"id": "2", "state": "archived"}  // Keys missing
]

The schema expects the keys to exist even if undefined, but JSON serialization removed them entirely, causing validation to fail.

Solution:

For now , until it get fixed , what you can do is:

• use null instead of undefined since null is preserved in JSON:

{
    id: "2",
    state: "archived",
    startedAt: null,   
    completedAt: null
}

• omit the keys entirely , this will make 'startedAt' and 'createdAt' optional in the inferred type:

{
   id: "2",
   state: "archived",
}

[wladimiiir]

Thanks for the info.

For now, I am just using patch-package to remove the validation as I don't really need it in my app. It would be nice to have an option in streamText/generateText to disableValidation?: boolean.

[shubham-021]

I tested the same code inside the repo and it worked correctly. Maybe the issue has already been fixed.