Immutable solution version
UI message stream vs text stream: picking the protocol for your useChat client
Complete solution
Two wire protocols in AI SDK 7 and when to use each: the UI message stream (default, supports tools) and the raw text stream (simple, custom clients).
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:
- Default to the UI message stream. It is the only protocol that supports tools, and useChat expects it unless you say otherwise.
- 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.
- 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.
- useObject uses its own object-streaming protocol over a text stream; do not point useChat at a useObject endpoint.
- 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 1 · 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>