Handling Vercel AI SDK streaming errors in Next.js

When you ship a chat feature with the Vercel AI SDK inside Next.js, next.js vercel ai sdk streaming errors are not a matter of if but when. Network interruptions, provider rate limits, and malformed JSON in a partial stream will surface as cryptic client exceptions if you only follow the quickstart. This guide lays out an ordered path to catch, classify, and recover from those failures without sacrificing the responsiveness that streaming buys you.

1. Isolate stream creation in the route handler

Use a Node.js runtime route segment. The Edge runtime hides some async stack traces and complicates catching downstream fetch errors. Wrap streamText in try/catch and return a structured error response before the stream starts; once headers are sent, you can only push error frames.

// app/api/chat/route.ts
import { streamText } from 'ai';
import { myProvider } from '@/lib/provider';

export const runtime = 'nodejs';

export async function POST(req: Request) {
  let prompt: string;
  try {
    const body = await req.json();
    prompt = body.prompt;
  } catch {
    return new Response('Invalid JSON', { status: 400 });
  }

  try {
    const result = streamText({
      model: myProvider('gpt-4o-mini'),
      prompt,
    });
    return result.toUIMessageStreamResponse();
  } catch (err) {
    // Catches only synchronous setup errors, not stream failures.
    return new Response('Model init failed', { status: 502 });
  }
}

The catch block above only captures failures in building the stream, not errors emitted while tokens flow. That distinction drives the rest of the design.

2. Classify errors: transport vs generation

A next.js vercel ai sdk streaming errors incident usually falls into two buckets. Transport errors abort the underlying fetch—DNS failure, TLS reset, or a 429 from the provider before the body opens. Generation errors arrive mid-stream: the model returns a finish reason of error, or the provider sends a malformed chunk.

Define a small error taxonomy so later steps can act on it:

export type StreamError =
  | { phase: 'transport'; code: 'ECONN' | 'RATE_LIMIT'; message: string }
  | { phase: 'generation'; code: 'MODEL_ERROR' | 'PARSE'; message: string };

You cannot throw these across the network boundary directly, but you can serialize them into the data stream.

3. Forward errors through the UI message stream

The Vercel AI SDK’s toUIMessageStreamResponse accepts an onError transform in older versions, or you use toDataStreamResponse({ getErrorMessage }) to map thrown stream errors to a client-visible string. Prefer the data stream protocol because useChat already parses it.

return result.toDataStreamResponse({
  getErrorMessage: (error) => {
    if (error instanceof RateLimitError) {
      return 'RATE_LIMIT';
    }
    return 'STREAM_FAILED';
  },
});

If you need richer objects, write a custom transform that calls controller.enqueue with a data- prefixed line. The client useChat receives these in data array.

Pitfall: returning a generic 500 from the route after the stream starts does nothing—the browser already read 200 with text/event-stream. You must emit an error part inside the stream or the client hangs until timeout.

4. Recover on the client with useChat

The useChat hook from @ai-sdk/react exposes error and reload. Wire onError to surface a banner, but keep the partial message in the DOM so the user keeps context.

'use client';
import { useChat } from '@ai-sdk/react';

export function Chat() {
  const { messages, input, handleInputChange, handleSubmit, error, reload } =
    useChat({ onError: (e) => console.error('stream error', e) });

  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>{m.content}</div>
      ))}
      {error && (
        <button onClick={() => reload()}>Retry last request</button>
      )}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
      </form>
    </div>
  );
}

Do not auto-call reload on every error. A provider-side 429 needs backoff; blind retry amplifies the load and gets you blocked.

5. Implement bounded retry with backoff

Add a small wrapper around reload that tracks attempt count and waits with jitter.

function useRetryableChat() {
  const chat = useChat();
  const attempts = useRef(0);

  const safeReload = async () => {
    if (attempts.current >= 3) return;
    const delay = Math.min(1000 * 2 ** attempts.current, 8000) + Math.random() * 500;
    await new Promise((r) => setTimeout(r, delay));
    attempts.current += 1;
    chat.reload();
  };
  return { ...chat, safeReload };
}

Server-side, accept an Idempotency-Key header so a retried POST does not double-charge usage or create duplicate generations. The gateway you front models with should honor it; for example, n4n.ai provides per-token metering and respects client routing directives, which makes retried requests auditable.

Tradeoff: longer backoff improves success but worsens perceived latency. For chat, cap at 3 attempts and show a manual retry button after the cap.

6. Degrade gracefully when a provider is unhealthy

If your route talks to a single model host, a regional outage becomes a hard next.js vercel ai sdk streaming errors page. Put a fallback chain in the server action: try primary, on RATE_LIMIT or ECONN switch model alias.

let result;
try {
  result = streamText({ model: primary, prompt });
} catch (e) {
  result = streamText({ model: secondary, prompt });
}

Better, use a gateway that performs automatic fallback when a provider is degraded. That converts a mid-stream abort into a slower but completed response, and the client code stays unchanged. This is one place where routing logic offloaded to the inference layer pays off immediately.

7. Log without leaking prompts or keys

Server logs should capture the error phase and model id, not the full prompt or provider credentials.

result.toDataStreamResponse({
  getErrorMessage: (error) => {
    console.error({ phase: 'stream', model: 'gpt-4o-mini', err: error.message });
    return 'STREAM_FAILED';
  },
});

In the client, log only the error code, not the raw error.message which may contain response bodies with tokens.

8. Simulate failures in development

You cannot fix next.js vercel ai sdk streaming errors you have not reproduced. Use a mock provider that throws after a few tokens to validate your wiring.

const flakyModel = {
  stream: async function* () {
    yield 'Hello';
    throw new Error('PARSE');
  },
};

Point your route at flakyModel via an env flag. Verify the client shows the retry UI and the server logs the phase. This catches missing getErrorMessage mapping before production traffic hits it.

9. Common pitfalls and tradeoffs

• Swallowing stream errors: returning new Response() after streamText starts loses the error. Always use the stream’s error mapping.
• Edge runtime stack traces: they truncate async causes. Use Node.js runtime for debuggability unless you need edge geo.
• CORS on retry: if the chat route is called from a different origin, ensure OPTIONS preflight returns 204 and the retry includes credentials.
• Partial UI state: useChat keeps the assistant message even on failure. Clear it only after a successful reload, or the user sees duplicated text.
• Over-aggressive fallback: switching models mid-conversation changes tone and price. Restrict fallback to same-family aliases.

The patterns above turn next.js vercel ai sdk streaming errors from opaque hangs into measurable, retryable events. Implement the route-level classification first, then layer client recovery; fallback at the gateway last.