MessageConversionError: convertToModelMessages failed on your history

TL;DR

A schema migration that added a new part type without updating the stored history produces this. Move system text to top-level instructions instead.

Steps

1. MessageConversionError fires inside convertToModelMessages, which means your UIMessage array is malformed before the model is ever involved.
2. const messages = await convertToModelMessages(uiMessages); // can throw
3. What to know:
4. The usual culprit is hand-built UIMessage objects: a part with a wrong type string, a missing role, or content parts the converter does not recognize.
5. Related: InvalidMessageRoleError (bad role value) and InvalidDataContentError (bad data part content). The errors reference groups them under inputs and message streams.
6. If messages come from persistence, validate them on load. A schema migration that added a new part type without updating the stored history produces this.
7. In v7, system-role messages inside messages/prompt are rejected unless allowSystemInMessages is true. Move system text to top-level instructions instead. Persisted histories containing { role: 'system' } entries hit this after upgrading.
8. UIMessageStreamError is the sibling for the streaming direction: the outgoing UI message stream contained an invalid part. Check custom createUIMessageStream / stream injection code.
9. Debug by converting in isolation with a try/catch and logging which message index fails. Binary-search the array if it is long.

When to use

You are seeing this: MessageConversionError fires inside convertToModelMessages, which means your UIMessage array is malformed before the model is ever involved. const messages = await convertToModelMessages(uiMessages); // can throw What to know: 1. Use this skill when you run into "MessageConversionError: convertToModelMessages failed on your history".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Verified against the live AI SDK docs 2026-09-26. The errors reference lists MessageConversionError and UIMessageStreamError under inputs and message streams. The v7 migration skill notes document the allowSystemInMessages behavior and moving system messages to instructions.