ai 6.0.34 → 6.0.36

package/dist/internal/index.js

@@ -153,7 +153,7 @@ var import_provider_utils2 = require("@ai-sdk/provider-utils");
 var import_provider_utils3 = require("@ai-sdk/provider-utils");
 
 // src/version.ts
-var VERSION = true ? "6.0.34" : "0.0.0-test";
+var VERSION = true ? "6.0.36" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({ url }) => {

package/dist/internal/index.mjs

@@ -128,7 +128,7 @@ import {
 } from "@ai-sdk/provider-utils";
 
 // src/version.ts
-var VERSION = true ? "6.0.34" : "0.0.0-test";
+var VERSION = true ? "6.0.36" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({ url }) => {

package/docs/02-foundations/04-tools.mdx

@@ -24,7 +24,7 @@ and [`streamText`](/docs/reference/ai-sdk-core/stream-text) by passing one or mo
 A tool consists of three properties:
 
 - **`description`**: An optional description of the tool that can influence when the tool is picked.
-- **`inputSchema`**: A [Zod schema](/docs/foundations/tools#schema-specification-and-validation-with-zod) or a [JSON schema](/docs/reference/ai-sdk-core/json-schema) that defines the input required for the tool to run. The schema is consumed by the LLM, and also used to validate the LLM tool calls.
+- **`inputSchema`**: A [Zod schema](/docs/reference/ai-sdk-core/zod-schema) or a [JSON schema](/docs/reference/ai-sdk-core/json-schema) that defines the input required for the tool to run. The schema is consumed by the LLM, and also used to validate the LLM tool calls.
 - **`execute`**: An optional async function that is called with the arguments from the tool call.
 
 <Note>

package/docs/07-reference/05-ai-sdk-errors/ai-ui-message-stream-error.mdx

@@ -0,0 +1,67 @@
+---
+title: AI_UIMessageStreamError
+description: Learn how to fix AI_UIMessageStreamError
+---
+
+# AI_UIMessageStreamError
+
+This error occurs when a UI message stream contains invalid or out-of-sequence chunks.
+
+Common causes:
+
+- Receiving a `text-delta` chunk without a preceding `text-start` chunk
+- Receiving a `text-end` chunk without a preceding `text-start` chunk
+- Receiving a `reasoning-delta` chunk without a preceding `reasoning-start` chunk
+- Receiving a `reasoning-end` chunk without a preceding `reasoning-start` chunk
+- Receiving a `tool-input-delta` chunk without a preceding `tool-input-start` chunk
+- Attempting to access a tool invocation that doesn't exist
+
+This error often surfaces when an upstream request fails **before any tokens are streamed** and a custom transport tries to write an inline error message to the UI stream without the proper start chunk.
+
+## Properties
+
+- `chunkType`: The type of chunk that caused the error (e.g., `text-delta`, `reasoning-end`, `tool-input-delta`)
+- `chunkId`: The ID associated with the failing chunk (part ID or toolCallId)
+- `message`: The error message with details about what went wrong
+
+## Checking for this Error
+
+You can check if an error is an instance of `AI_UIMessageStreamError` using:
+
+```typescript
+import { UIMessageStreamError } from 'ai';
+
+if (UIMessageStreamError.isInstance(error)) {
+  console.log('Chunk type:', error.chunkType);
+  console.log('Chunk ID:', error.chunkId);
+  // Handle the error
+}
+```
+
+## Common Solutions
+
+1. **Ensure proper chunk ordering**: Always send a `*-start` chunk before any `*-delta` or `*-end` chunks for the same ID:
+
+   ```typescript
+   // Correct order
+   writer.write({ type: 'text-start', id: 'my-text' });
+   writer.write({ type: 'text-delta', id: 'my-text', delta: 'Hello' });
+   writer.write({ type: 'text-end', id: 'my-text' });
+   ```
+
+2. **Verify IDs match**: Ensure the `id` used in `*-delta` and `*-end` chunks matches the `id` used in the corresponding `*-start` chunk.
+
+3. **Handle error paths correctly**: When writing error messages in custom transports, ensure you emit the full start/delta/end sequence:
+
+   ```typescript
+   // When handling errors in custom transports
+   writer.write({ type: 'text-start', id: errorId });
+   writer.write({
+     type: 'text-delta',
+     id: errorId,
+     delta: 'Request failed...',
+   });
+   writer.write({ type: 'text-end', id: errorId });
+   ```
+
+4. **Check stream producer logic**: Review your streaming implementation to ensure chunks are sent in the correct order, especially when dealing with concurrent operations or merged streams.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "6.0.34",
+  "version": "6.0.36",
   "description": "AI SDK by Vercel - The AI Toolkit for TypeScript and JavaScript",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -42,9 +42,9 @@
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
-    "@ai-sdk/gateway": "3.0.14",
+    "@ai-sdk/gateway": "3.0.15",
     "@ai-sdk/provider": "3.0.3",
-    "@ai-sdk/provider-utils": "4.0.6"
+    "@ai-sdk/provider-utils": "4.0.7"
   },
   "devDependencies": {
     "@edge-runtime/vm": "^5.0.0",

package/src/error/index.ts

@@ -26,6 +26,7 @@ export { NoSpeechGeneratedError } from './no-speech-generated-error';
 export { NoSuchToolError } from './no-such-tool-error';
 export { ToolCallRepairError } from './tool-call-repair-error';
 export { UnsupportedModelVersionError } from './unsupported-model-version-error';
+export { UIMessageStreamError } from './ui-message-stream-error';
 
 export { InvalidDataContentError } from '../prompt/invalid-data-content-error';
 export { InvalidMessageRoleError } from '../prompt/invalid-message-role-error';

package/src/error/ui-message-stream-error.ts

@@ -0,0 +1,48 @@
+import { AISDKError } from '@ai-sdk/provider';
+
+const name = 'AI_UIMessageStreamError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Error thrown when a UI message stream contains invalid or out-of-sequence chunks.
+ *
+ * This typically occurs when:
+ * - A delta chunk is received without a corresponding start chunk
+ * - An end chunk is received without a corresponding start chunk
+ * - A tool invocation is not found for the given toolCallId
+ *
+ * @see https://ai-sdk.dev/docs/reference/ai-sdk-errors/ai-ui-message-stream-error
+ */
+export class UIMessageStreamError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  /**
+   * The type of chunk that caused the error (e.g., 'text-delta', 'reasoning-end').
+   */
+  readonly chunkType: string;
+
+  /**
+   * The ID associated with the failing chunk (part ID or toolCallId).
+   */
+  readonly chunkId: string;
+
+  constructor({
+    chunkType,
+    chunkId,
+    message,
+  }: {
+    chunkType: string;
+    chunkId: string;
+    message: string;
+  }) {
+    super({ name, message });
+
+    this.chunkType = chunkType;
+    this.chunkId = chunkId;
+  }
+
+  static isInstance(error: unknown): error is UIMessageStreamError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/ui/process-ui-message-stream.test.ts

@@ -8,6 +8,7 @@ import {
 } from './process-ui-message-stream';
 import { InferUIMessageData, UIMessage } from './ui-messages';
 import { beforeEach, describe, it, expect, vi } from 'vitest';
+import { UIMessageStreamError } from '../error/ui-message-stream-error';
 
 function createUIMessageStream(parts: UIMessageChunk[]) {
   return convertArrayToReadableStream(parts);
@@ -224,6 +225,247 @@ describe('processUIMessageStream', () => {
     });
   });
 
+  describe('malformed stream errors', () => {
+    it('should throw descriptive error when text-delta is received without text-start', async () => {
+      const stream = createUIMessageStream([
+        { type: 'start', messageId: 'msg-123' },
+        { type: 'start-step' },
+        { type: 'text-delta', id: 'text-1', delta: 'Hello' },
+      ]);
+
+      state = createStreamingUIMessageState({
+        messageId: 'msg-123',
+        lastMessage: undefined,
+      });
+
+      await expect(
+        consumeStream({
+          stream: processUIMessageStream({
+            stream,
+            runUpdateMessageJob,
+            onError: error => {
+              throw error;
+            },
+          }),
+          onError: error => {
+            throw error;
+          },
+        }),
+      ).rejects.toThrow(
+        'Received text-delta for missing text part with ID "text-1". ' +
+          'Ensure a "text-start" chunk is sent before any "text-delta" chunks.',
+      );
+    });
+
+    it('should throw descriptive error when reasoning-delta is received without reasoning-start', async () => {
+      const stream = createUIMessageStream([
+        { type: 'start', messageId: 'msg-123' },
+        { type: 'start-step' },
+        { type: 'reasoning-delta', id: 'reasoning-1', delta: 'Thinking...' },
+      ]);
+
+      state = createStreamingUIMessageState({
+        messageId: 'msg-123',
+        lastMessage: undefined,
+      });
+
+      await expect(
+        consumeStream({
+          stream: processUIMessageStream({
+            stream,
+            runUpdateMessageJob,
+            onError: error => {
+              throw error;
+            },
+          }),
+          onError: error => {
+            throw error;
+          },
+        }),
+      ).rejects.toThrow(
+        'Received reasoning-delta for missing reasoning part with ID "reasoning-1". ' +
+          'Ensure a "reasoning-start" chunk is sent before any "reasoning-delta" chunks.',
+      );
+    });
+
+    it('should throw descriptive error when tool-input-delta is received without tool-input-start', async () => {
+      const stream = createUIMessageStream([
+        { type: 'start', messageId: 'msg-123' },
+        { type: 'start-step' },
+        {
+          type: 'tool-input-delta',
+          toolCallId: 'tool-1',
+          inputTextDelta: '{"key":',
+        },
+      ]);
+
+      state = createStreamingUIMessageState({
+        messageId: 'msg-123',
+        lastMessage: undefined,
+      });
+
+      await expect(
+        consumeStream({
+          stream: processUIMessageStream({
+            stream,
+            runUpdateMessageJob,
+            onError: error => {
+              throw error;
+            },
+          }),
+          onError: error => {
+            throw error;
+          },
+        }),
+      ).rejects.toThrow(
+        'Received tool-input-delta for missing tool call with ID "tool-1". ' +
+          'Ensure a "tool-input-start" chunk is sent before any "tool-input-delta" chunks.',
+      );
+    });
+
+    it('should throw descriptive error when text-end is received without text-start', async () => {
+      const stream = createUIMessageStream([
+        { type: 'start', messageId: 'msg-123' },
+        { type: 'start-step' },
+        { type: 'text-end', id: 'text-1' },
+      ]);
+
+      state = createStreamingUIMessageState({
+        messageId: 'msg-123',
+        lastMessage: undefined,
+      });
+
+      await expect(
+        consumeStream({
+          stream: processUIMessageStream({
+            stream,
+            runUpdateMessageJob,
+            onError: error => {
+              throw error;
+            },
+          }),
+          onError: error => {
+            throw error;
+          },
+        }),
+      ).rejects.toThrow(
+        'Received text-end for missing text part with ID "text-1". ' +
+          'Ensure a "text-start" chunk is sent before any "text-end" chunks.',
+      );
+    });
+
+    it('should throw descriptive error when reasoning-end is received without reasoning-start', async () => {
+      const stream = createUIMessageStream([
+        { type: 'start', messageId: 'msg-123' },
+        { type: 'start-step' },
+        { type: 'reasoning-end', id: 'reasoning-1' },
+      ]);
+
+      state = createStreamingUIMessageState({
+        messageId: 'msg-123',
+        lastMessage: undefined,
+      });
+
+      await expect(
+        consumeStream({
+          stream: processUIMessageStream({
+            stream,
+            runUpdateMessageJob,
+            onError: error => {
+              throw error;
+            },
+          }),
+          onError: error => {
+            throw error;
+          },
+        }),
+      ).rejects.toThrow(
+        'Received reasoning-end for missing reasoning part with ID "reasoning-1". ' +
+          'Ensure a "reasoning-start" chunk is sent before any "reasoning-end" chunks.',
+      );
+    });
+
+    it('should throw UIMessageStreamError with correct properties for text-delta without text-start', async () => {
+      const stream = createUIMessageStream([
+        { type: 'start', messageId: 'msg-123' },
+        { type: 'start-step' },
+        { type: 'text-delta', id: 'missing-id', delta: 'Hello' },
+      ]);
+
+      state = createStreamingUIMessageState({
+        messageId: 'msg-123',
+        lastMessage: undefined,
+      });
+
+      let caughtError: unknown;
+      try {
+        await consumeStream({
+          stream: processUIMessageStream({
+            stream,
+            runUpdateMessageJob,
+            onError: error => {
+              throw error;
+            },
+          }),
+          onError: error => {
+            throw error;
+          },
+        });
+      } catch (error) {
+        caughtError = error;
+      }
+
+      expect(UIMessageStreamError.isInstance(caughtError)).toBe(true);
+      expect((caughtError as UIMessageStreamError).chunkType).toBe(
+        'text-delta',
+      );
+      expect((caughtError as UIMessageStreamError).chunkId).toBe('missing-id');
+    });
+
+    it('should throw UIMessageStreamError with correct properties for tool-input-delta without tool-input-start', async () => {
+      const stream = createUIMessageStream([
+        { type: 'start', messageId: 'msg-123' },
+        { type: 'start-step' },
+        {
+          type: 'tool-input-delta',
+          toolCallId: 'missing-tool-id',
+          inputTextDelta: '{"key":',
+        },
+      ]);
+
+      state = createStreamingUIMessageState({
+        messageId: 'msg-123',
+        lastMessage: undefined,
+      });
+
+      let caughtError: unknown;
+      try {
+        await consumeStream({
+          stream: processUIMessageStream({
+            stream,
+            runUpdateMessageJob,
+            onError: error => {
+              throw error;
+            },
+          }),
+          onError: error => {
+            throw error;
+          },
+        });
+      } catch (error) {
+        caughtError = error;
+      }
+
+      expect(UIMessageStreamError.isInstance(caughtError)).toBe(true);
+      expect((caughtError as UIMessageStreamError).chunkType).toBe(
+        'tool-input-delta',
+      );
+      expect((caughtError as UIMessageStreamError).chunkId).toBe(
+        'missing-tool-id',
+      );
+    });
+  });
+
   describe('server-side tool roundtrip', () => {
     beforeEach(async () => {
       const stream = createUIMessageStream([

package/src/ui/process-ui-message-stream.ts

@@ -1,4 +1,5 @@
 import { FlexibleSchema, validateTypes } from '@ai-sdk/provider-utils';
+import { UIMessageStreamError } from '../error/ui-message-stream-error';
 import { ProviderMetadata } from '../types';
 import { FinishReason } from '../types/language-model';
 import {
@@ -108,9 +109,11 @@ export function processUIMessageStream<UI_MESSAGE extends UIMessage>({
             );
 
             if (toolInvocation == null) {
-              throw new Error(
-                `no tool invocation found for tool call ${toolCallId}`,
-              );
+              throw new UIMessageStreamError({
+                chunkType: 'tool-invocation',
+                chunkId: toolCallId,
+                message: `No tool invocation found for tool call ID "${toolCallId}".`,
+              });
             }
 
             return toolInvocation;
@@ -313,6 +316,15 @@ export function processUIMessageStream<UI_MESSAGE extends UIMessage>({
 
             case 'text-delta': {
               const textPart = state.activeTextParts[chunk.id];
+              if (textPart == null) {
+                throw new UIMessageStreamError({
+                  chunkType: 'text-delta',
+                  chunkId: chunk.id,
+                  message:
+                    `Received text-delta for missing text part with ID "${chunk.id}". ` +
+                    `Ensure a "text-start" chunk is sent before any "text-delta" chunks.`,
+                });
+              }
               textPart.text += chunk.delta;
               textPart.providerMetadata =
                 chunk.providerMetadata ?? textPart.providerMetadata;
@@ -322,6 +334,15 @@ export function processUIMessageStream<UI_MESSAGE extends UIMessage>({
 
             case 'text-end': {
               const textPart = state.activeTextParts[chunk.id];
+              if (textPart == null) {
+                throw new UIMessageStreamError({
+                  chunkType: 'text-end',
+                  chunkId: chunk.id,
+                  message:
+                    `Received text-end for missing text part with ID "${chunk.id}". ` +
+                    `Ensure a "text-start" chunk is sent before any "text-end" chunks.`,
+                });
+              }
               textPart.state = 'done';
               textPart.providerMetadata =
                 chunk.providerMetadata ?? textPart.providerMetadata;
@@ -345,6 +366,15 @@ export function processUIMessageStream<UI_MESSAGE extends UIMessage>({
 
             case 'reasoning-delta': {
               const reasoningPart = state.activeReasoningParts[chunk.id];
+              if (reasoningPart == null) {
+                throw new UIMessageStreamError({
+                  chunkType: 'reasoning-delta',
+                  chunkId: chunk.id,
+                  message:
+                    `Received reasoning-delta for missing reasoning part with ID "${chunk.id}". ` +
+                    `Ensure a "reasoning-start" chunk is sent before any "reasoning-delta" chunks.`,
+                });
+              }
               reasoningPart.text += chunk.delta;
               reasoningPart.providerMetadata =
                 chunk.providerMetadata ?? reasoningPart.providerMetadata;
@@ -354,6 +384,15 @@ export function processUIMessageStream<UI_MESSAGE extends UIMessage>({
 
             case 'reasoning-end': {
               const reasoningPart = state.activeReasoningParts[chunk.id];
+              if (reasoningPart == null) {
+                throw new UIMessageStreamError({
+                  chunkType: 'reasoning-end',
+                  chunkId: chunk.id,
+                  message:
+                    `Received reasoning-end for missing reasoning part with ID "${chunk.id}". ` +
+                    `Ensure a "reasoning-start" chunk is sent before any "reasoning-end" chunks.`,
+                });
+              }
               reasoningPart.providerMetadata =
                 chunk.providerMetadata ?? reasoningPart.providerMetadata;
               reasoningPart.state = 'done';
@@ -440,6 +479,15 @@ export function processUIMessageStream<UI_MESSAGE extends UIMessage>({
 
             case 'tool-input-delta': {
               const partialToolCall = state.partialToolCalls[chunk.toolCallId];
+              if (partialToolCall == null) {
+                throw new UIMessageStreamError({
+                  chunkType: 'tool-input-delta',
+                  chunkId: chunk.toolCallId,
+                  message:
+                    `Received tool-input-delta for missing tool call with ID "${chunk.toolCallId}". ` +
+                    `Ensure a "tool-input-start" chunk is sent before any "tool-input-delta" chunks.`,
+                });
+              }
 
               partialToolCall.text += chunk.inputTextDelta;