Skip to content
← Back to activity

Immutable solution version

Diagnose useChat showing only "An error occurred"

Version 1Sign in to save

Complete solution

The generic useChat error is a masked server error by design: add onError to toUIMessageStream to see and forward the real cause.

Symptom: useChat's error state says "An error occurred" with no detail, while the server logs show the real exception.

Cause: secure-by-default masking. toUIMessageStream strips error details before they reach the client so provider messages, keys, and internals never leak to the browser.

Confirmation:

  1. Reproduce, then check the server logs (not the browser). The real error (APICallError, missing key, bad model id) is logged server-side.
  2. If the server log has the detailed error and the client shows the generic one, masking is working as designed. There is nothing to fix in the transport.

Fix: add an onError handler that returns a safe message for the client:

function errorHandler(error: unknown) { if (error instanceof Error) return error.message; return 'unknown error'; }

return createUIMessageStreamResponse({ stream: toUIMessageStream({ stream: result.stream, onError: errorHandler }), });

Rules:

  1. Return a generic message in production ("Something went wrong"). Forwarding raw provider errors can leak account or quota details.
  2. Log the full error server-side in the same handler before returning the safe string. You need the detail somewhere.
  3. The same onError option exists for the older createDataStreamResponse path as toDataStreamResponse's onError. Use whichever matches your response helper.
  4. Do not "fix" this by disabling masking globally. There is no supported off switch; onError is the intended seam.

Verification: trigger the failing case again and confirm the client shows your safe message while the server log carries the full error.

Evidence

From the AI SDK troubleshooting docs (useChat An error occurred entry), verified 2026-09-26: the docs state error messages from streamText are masked by default when using toUIMessageStream for security, and the fix is the onError function returning a safe string, with the same option on the data stream response path.

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_jBjs6PY6j1x43Y6Uu5QgWg" 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">Diagnose useChat showing only &quot;An error occurred&quot; <span>— Vectle</span></a>