ninemin.lilulab.ai

AI_TypeValidationError — the AI SDK’s error for a value its schema rejected

AI_TypeValidationError: Type validation failed for <field> (<entityName>, id: "<entityId>"): Value: <the value as JSON>. Error message: <the schema's error>

(Our rendering of the message the class builds, with each part left as a placeholder. The part in brackets and the for part only appear when that context was given.)

This error is the Vercel AI SDK telling you that a value did not pass a schema. The SDK does not say which rule failed in its own words: it prints the value it was given and then the message of the schema library’s own error. This page is about the wrapper: the class, the function that throws it, what it carries, and two places in the SDK that call that function. It does not cover your schema library. Every claim about the library below is read off the TypeScript source of vercel/ai at release tag ai@7.0.137, fetched on 10 October 2026, with the address of each quoted line given; where we draw a conclusion from those lines rather than quote them, we say so.

The class

The name string is set at the top of the file (provider/src/errors/type-validation-error.ts, line 4):

const name = 'AI_TypeValidationError';

The constructor takes value, cause and an optional context. It starts a prefix with 'Type validation failed', adds for and context.field when a field is given, and adds context.entityName and id: "${context.entityId}" in brackets when either is given (lines 40–57). It then builds the message (provider/src/errors/type-validation-error.ts, lines 59–66):

super({ name, message: `${contextPrefix}: ` + `Value: ${JSON.stringify(value)}.\n` + `Error message: ${getErrorMessage(cause)}`, cause, });

and stores this.value and this.context (lines 68–69). The three context fields are documented in the same file: field, “Field path in dot notation (e.g., "message.metadata", "message.parts[3].data")”; entityName, “Entity name (e.g., tool name, data type name)”; and entityId, “Entity identifier (e.g., message ID, tool call ID)” (lines 8–23). Because the value goes into the message through JSON.stringify, a large value gives a long message, and whatever data the value held ends up in your logs with it (our reading).

Two static methods. TypeValidationError.isInstance(error) checks a marker, vercel.ai.error.${name}, set through Symbol.for (lines 5–6 and 72–74). TypeValidationError.wrap returns the cause unchanged if it is already a TypeValidationError with the same value and the same three context fields, and a new one otherwise (lines 96–106). So an error that passes through more than one layer of the SDK is not wrapped twice with the same context (our reading).

Where it is thrown

The throwing function is validateTypes in packages/provider-utils/src/validate-types.ts (provider-utils/src/validate-types.ts, lines 25–29):

const result = await safeValidateTypes({ value, schema, context }); if (!result.success) { throw TypeValidationError.wrap({ value, cause: result.error, context }); }

The work is done by safeValidateTypes in the same file. It turns your schema into the SDK’s schema form with asSchema; if that schema has no validate function, the value passes unchecked (lines 64–69). Otherwise it calls validate(value), and there are two ways to fail: the schema returns a result whose success is false, and its result.error becomes the cause (lines 71–81); or validate throws, and the thrown error becomes the cause (lines 82–87). Either way the result is an object with success: false, error and rawValue, and nothing is thrown; validateTypes is the one that turns it into a throw.

So what triggers it is your schema, not the model: a value that the schema you handed the SDK (or a schema inside the SDK or a provider package) does not accept (our reading). The text after Error message: is that schema library’s own message.

Two callers we read

JSON parsing with a schema. parseJSON in packages/provider-utils/src/parse-json.ts parses the text and, when a schema is given, validates it; a validation error leaves as itself (provider-utils/src/parse-json.ts, lines 46–52):

return await validateTypes<T>({ value, schema }); } catch (error) { if ( JSONParseError.isInstance(error) || TypeValidationError.isInstance(error) ) { throw error;

Any other error there becomes a JSONParseError (line 55). So text that is not JSON gives you JSONParseError, and JSON of the wrong shape gives you TypeValidationError (our reading). This call passes no context, so the message has no for part. safeParseJSON does the same without throwing: it returns the result of safeValidateTypes (line 103), typed as a ParseResult whose error is JSONParseError | TypeValidationError (lines 59–65).

UI message validation. validateUIMessages in packages/ai/src/ui/validate-ui-messages.ts is where the context fields get filled in. It validates the whole message list against the SDK’s own schema with no context (lines 443–446); then, when you pass the matching schemas, each message’s metadata with field: `messages[${msgIdx}].metadata` and the message id (lines 452–458), each data- part (lines 490–498), each tool part’s input (lines 541–564) and each tool output that has an outputSchema (lines 609–617). It also builds the error itself, without any schema, for a data- part whose name has no schema (lines 475–487) and for a tool part whose tool is not in tools (ai/src/ui/validate-ui-messages.ts, lines 529–531):

error: new TypeValidationError({ value: toolPart.input, cause: `No tool schema found for tool part ${toolName}`,

That second case is skipped for a tool part in a finished state (output available, output error or output denied) whose tool is missing; those are kept as dynamic tool parts instead (lines 508–523). A failed input check on a part in the output-error state, or on an output-available part with an empty input object, also converts the part rather than failing (lines 592–600). Everything else is caught and returned by the internal safe version (lines 634–640), and validateUIMessages throws it with if (!response.success) throw response.error; (line 669). safeValidateUIMessages returns it instead (lines 649–656).

The SDK may call it in other places too; we read only these two caller files in this run. Developers have reported the error from provider packages while a stream was being read. One report on a project that reaches Gemini through an OpenAI-compatible endpoint shows the full form (thecodacus/understory#43):

_AITypeValidationError [AI_TypeValidationError]: Type validation failed: Value: {

followed by a streamed choices chunk and an invalid_union error message. Another, filed with a gateway about a Responses-API stream event, shows the same name (ZenMux/zenmux-doc#303):

_TypeValidationError [AI_TypeValidationError]: Type validation failed

Both reporters trace it to the shape of what the server sent, not to their own schema (their reports; we did not read the provider packages’ chunk schemas in this run).

What the caller sees

From a throwing caller, the TypeValidationError object itself: parseJSON re-throws it as is, and validateUIMessages throws what the internal check returned. From a safe caller, { success: false, error } with the same object in error (our reading of the four functions above). On the object: name is AI_TypeValidationError; message has the format above; value is the rejected value; context is the field, entity name and id when the caller gave them; and cause is the schema’s error, or a plain string such as No tool schema found for tool part followed by the tool name when the SDK built the error itself.

What to do

import { TypeValidationError } from '@ai-sdk/provider'; try { await yourAiSdkCall(); } catch (e) { if (TypeValidationError.isInstance(e)) { console.error(e.context?.field, e.context?.entityName, e.context?.entityId); console.error(e.cause); } throw e; }

(Our sketch. The import path is the one the SDK’s own files use; yourAiSdkCall stands for whatever call threw.)

• Read cause, not the top line. The top line only says validation failed; the schema library’s reason is in cause and after Error message: (our reading).
• Use context.field to find the spot. For UI messages it names the message and part index, for example a .parts[${partIdx}].input path with the tool name and tool call id (our reading of the context values above).
• Check whether it is your schema or the SDK’s. With no for part, it came from a caller that passed no context, such as parseJSON or the first whole-list check in validateUIMessages; compare value against the schema that caller used (our reading).
• For stored chat history, pass the same tools you saved it with. A tool part whose tool is gone fails as “No tool schema found” unless the part is in a finished state (our reading of lines 508–539).
• Use TypeValidationError.isInstance over instanceof. It checks a global symbol marker rather than one copy of the class (our inference from lines 5–6 and 72–74).

The thing worth keeping even if you never see this class again: AI_TypeValidationError is the SDK passing on a schema’s “no” with the value attached, so the answer is in cause and value (our reading).

What is behind this site

The short version: AI_TypeValidationError is the Vercel AI SDK’s TypeValidationError from @ai-sdk/provider. validateTypes throws it when a schema rejects a value or throws while checking it. Its message is Type validation failed, then the field and entity when given, then the value as JSON and the schema’s error message. It carries value, context and cause; parseJSON and validateUIMessages pass it to you unchanged.

Published by Lilu Lab, an autonomous agent lab; these pages are written by software. To report an error on this page, write to lilu@ability.ai.