fix(ai): throw error for missing start chunks in processUIMessageStream

packages/ai/src/ui/process-ui-message-stream.test.ts

@@ -224,6 +224,105 @@ 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.',
+      );
+    });
+  });
+
   describe('server-side tool roundtrip', () => {
     beforeEach(async () => {
       const stream = createUIMessageStream([

packages/ai/src/ui/process-ui-message-stream.ts

@@ -57,14 +57,14 @@ export function createStreamingUIMessageState<UI_MESSAGE extends UIMessage>({
       lastMessage?.role === 'assistant'
         ? lastMessage
         : ({
-            id: messageId,
-            metadata: undefined,
-            role: 'assistant',
-            parts: [] as UIMessagePart<
-              InferUIMessageData<UI_MESSAGE>,
-              InferUIMessageTools<UI_MESSAGE>
-            >[],
-          } as UI_MESSAGE),
+          id: messageId,
+          metadata: undefined,
+          role: 'assistant',
+          parts: [] as UIMessagePart<
+            InferUIMessageData<UI_MESSAGE>,
+            InferUIMessageTools<UI_MESSAGE>
+          >[],
+        } as UI_MESSAGE),
     activeTextParts: {},
     activeReasoningParts: {},
     partialToolCalls: {},
@@ -123,33 +123,33 @@ export function processUIMessageStream<UI_MESSAGE extends UIMessage>({
               providerExecuted?: boolean;
               title?: string;
             } & (
-              | {
+                | {
                   state: 'input-streaming';
                   input: unknown;
                   providerExecuted?: boolean;
                 }
-              | {
+                | {
                   state: 'input-available';
                   input: unknown;
                   providerExecuted?: boolean;
                   providerMetadata?: ProviderMetadata;
                 }
-              | {
+                | {
                   state: 'output-available';
                   input: unknown;
                   output: unknown;
                   providerExecuted?: boolean;
                   preliminary?: boolean;
                 }
-              | {
+                | {
                   state: 'output-error';
                   input: unknown;
                   rawInput?: unknown;
                   errorText: string;
                   providerExecuted?: boolean;
                   providerMetadata?: ProviderMetadata;
                 }
-            ),
+              ),
           ) {
             const part = state.message.parts.find(
               part =>
@@ -206,28 +206,28 @@ export function processUIMessageStream<UI_MESSAGE extends UIMessage>({
               providerExecuted?: boolean;
               title?: string;
             } & (
-              | {
+                | {
                   state: 'input-streaming';
                   input: unknown;
                 }
-              | {
+                | {
                   state: 'input-available';
                   input: unknown;
                   providerMetadata?: ProviderMetadata;
                 }
-              | {
+                | {
                   state: 'output-available';
                   input: unknown;
                   output: unknown;
                   preliminary: boolean | undefined;
                 }
-              | {
+                | {
                   state: 'output-error';
                   input: unknown;
                   errorText: string;
                   providerMetadata?: ProviderMetadata;
                 }
-            ),
+              ),
           ) {
             const part = state.message.parts.find(
               part =>
@@ -313,6 +313,12 @@ export function processUIMessageStream<UI_MESSAGE extends UIMessage>({
 
             case 'text-delta': {
               const textPart = state.activeTextParts[chunk.id];
+              if (textPart == null) {
+                throw new Error(
+                  `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 +328,12 @@ export function processUIMessageStream<UI_MESSAGE extends UIMessage>({
 
             case 'text-end': {
               const textPart = state.activeTextParts[chunk.id];
+              if (textPart == null) {
+                throw new Error(
+                  `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 +357,12 @@ export function processUIMessageStream<UI_MESSAGE extends UIMessage>({
 
             case 'reasoning-delta': {
               const reasoningPart = state.activeReasoningParts[chunk.id];
+              if (reasoningPart == null) {
+                throw new Error(
+                  `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 +372,12 @@ export function processUIMessageStream<UI_MESSAGE extends UIMessage>({
 
             case 'reasoning-end': {
               const reasoningPart = state.activeReasoningParts[chunk.id];
+              if (reasoningPart == null) {
+                throw new Error(
+                  `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 +464,12 @@ export function processUIMessageStream<UI_MESSAGE extends UIMessage>({
 
             case 'tool-input-delta': {
               const partialToolCall = state.partialToolCalls[chunk.toolCallId];
+              if (partialToolCall == null) {
+                throw new Error(
+                  `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;
 
@@ -684,12 +714,12 @@ export function processUIMessageStream<UI_MESSAGE extends UIMessage>({
                 const existingUIPart =
                   dataChunk.id != null
                     ? (state.message.parts.find(
-                        chunkArg =>
-                          dataChunk.type === chunkArg.type &&
-                          dataChunk.id === chunkArg.id,
-                      ) as
-                        | DataUIPart<InferUIMessageData<UI_MESSAGE>>
-                        | undefined)
+                      chunkArg =>
+                        dataChunk.type === chunkArg.type &&
+                        dataChunk.id === chunkArg.id,
+                    ) as
+                      | DataUIPart<InferUIMessageData<UI_MESSAGE>>
+                      | undefined)
                     : undefined;
 
                 if (existingUIPart != null) {