fix(ai): improve type validation error messages with field paths and entity identifiers

[felixarntz]

Background

Validation errors from safeValidateUIMessages and streaming validation lacked context about what was being validated, making debugging difficult.

Before:

Type validation failed: Value: undefined.
Error message: Required

After:

Type validation failed for messages[0].metadata (id: "msg-123"): Value: undefined.
Error message: Required

Alternative to #10154: This PR focuses on addressing the lack of context closer to the root, and includes the full field identifier to help finding the culprit more quickly.

Summary

Added optional context tracking to TypeValidationError to include field paths (e.g., messages[0].parts[1].data) and entity identifiers (e.g., message ID, tool call ID) in validation error messages.

Approach:

• Introduced TypeValidationContext interface with field, entityName, and entityId properties
• Extended TypeValidationError and validation utilities to accept and format context
• Updated all validation call sites in validate-ui-messages.ts and process-ui-message-stream.ts to provide context with index tracking

The change is backward compatible (context is optional) and includes a minor performance improvement by consolidating data/tool validation into a single loop.

Manual Verification

To verify the improved error messages:

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

try {
  await validateUIMessages({
    messages: [{
      id: 'msg-123',
      role: 'user',
      metadata: { userId: 123 }, // wrong type
      parts: [{ type: 'text', text: 'Hello' }],
    }],
    metadataSchema: z.object({ userId: z.string() }),
  });
} catch (error) {
  console.log(error.message);
  // Shows: "Type validation failed for messages[0].metadata (id: "msg-123"): ..."
}

Checklist

• Tests have been added / updated (for bug fixes / features)
• Documentation has been added / updated (for bug fixes / features)
• A patch changeset for relevant packages has been added (for bug fixes / features - run pnpm changeset in the project root)
• I have reviewed this pull request (self-review)

Future Work

Issue #10137 also mentions fixing documentation for metadata schema examples. That's not the primary issue raised though, and will be addressed in a separate PR.

Related Issues

Fixes #10137

[gr2m]

Looks good! PR includes updates to the provider package but it does not alter the spec, so I don't think we should consider it a breaking change. But would like @lgrammel to confirm

[gr2m]

TIL - nice way to get the index in a for loop

[gr2m]

@felixarntz and I tested with

• ai@latest, @ai-sdk/openai@0.0.0-01d6317c-20260129172110
• ai@0.0.0-01d6317c-20260129172110, @ai-sdk/openai@latest

✅ good to go