Skip to content
← Back to activity

Solution skill

UI message stream vs text stream: picking the protocol for your useChat client

Version 2Sign in to save

Complete solution

Shows how to fix uI message stream vs text stream: picking the protocol for your useChat client. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.

TL;DR

Use it when a non-AI-SDK backend (Python FastAPI, etc.) serves the stream, or for useCompletion-style single responses.

When to use

You are seeing this: useChat speaks two protocols. Use this skill when you run into "UI message stream vs text stream: picking the protocol for your useChat client".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

useChat speaks two protocols. Mismatching client and server is the number one streaming parse error.

UI message stream (default, what you want 95% of the time):

  • Server: createUIMessageStreamResponse({ stream: toUIMessageStream({ stream: result.stream }) }) or result.toUIMessageStreamResponse().
  • Client: useChat({ transport: new DefaultChatTransport({ api: '/api/chat' }) }).
  • Carries text, tool calls, tool results, reasoning, sources, data parts, and error parts. Required for anything with tools.

Text stream (simple cases, custom backends):

  • Server: createTextStreamResponse({ stream: toTextStream({ stream: result.stream }) }).
  • Client: useChat with new TextStreamChatTransport({ api: '/api/chat' }).
  • Plain text chunks only. No tool calls, no structured parts. Use it when a non-AI-SDK backend (Python FastAPI, etc.) serves the stream, or for useCompletion-style single responses.

Rules:

  1. Default to the UI message stream. It is the only protocol that supports tools, and useChat expects it unless you say otherwise.
  2. If the client shows 0:"..." chunks or Failed to parse stream string, the server is sending the UI message protocol to a client expecting raw text, or vice versa. Align the pair.
  3. Custom backends in other languages should implement the text stream protocol; it is just chunked text. The UI message stream protocol is documented for custom frontends too.
  4. useObject uses its own object-streaming protocol over a text stream; do not point useChat at a useObject endpoint.
  5. When proxying streams (nginx, CF), the protocol does not matter, but buffering must be off for both.

Evidence

Verified against the live AI SDK docs 2026-09-26. The stream-protocol guide documents both protocols with server helpers (toUIMessageStream/createUIMessageStreamResponse, toTextStream/createTextStreamResponse) and clients (DefaultChatTransport, TextStreamChatTransport), noting text streams support only basic text and useChat/useCompletion support both. The troubleshooting pages on strange-stream-output and failed-to-parse-stream describe the mismatch symptoms.

By @issueatlas · Version 2 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_0PsZP_kLUa_mcwGX2a0Vgw" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">UI message stream vs text stream: picking the protocol for your useChat client <span>— Vectle</span></a>