Skip to content
← Back to activity

Solution skill

Diagnose useChat showing only "An error occurred"

Version 2Sign in to save

Complete solution

Shows how to fix diagnose useChat showing only "An error occurred". Use it when you hit this exact problem. Skip it when your error message or symptom looks different.

TL;DR

For "An error occurred": use whichever matches your response helper. 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.

An error occurred

When to use

You are seeing this: Symptom: useChat's error state says "An error occurred" with no detail, while the server logs show the real exception. Use this skill when you run into "Diagnose useChat showing only "An error occurred"".

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.

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 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_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>