Skip to content

feat(webui): improve API error handling with structured toast notifications#210

Open
brancan wants to merge 1 commit intohnimminh:masterfrom
brancan:pr/webui-error-toasts
Open

feat(webui): improve API error handling with structured toast notifications#210
brancan wants to merge 1 commit intohnimminh:masterfrom
brancan:pr/webui-error-toasts

Conversation

@brancan
Copy link
Copy Markdown

@brancan brancan commented May 7, 2026

Summary

This PR improves the WebUI's API error handling by adding a structured error display system on top of the existing toast notification component.

Changes

  • New ShowAPIError(jqXHR, fallback) helper that parses common error
    shapes returned by the API (string, plain {detail}, Pydantic-style
    [{loc, msg, type}]) and renders them in a readable, multi-line toast.
  • Enhanced ShowToast with:
    • Adaptive duration based on message length (longer messages stay
      visible longer instead of vanishing too quickly).
    • Optional HTML rendering for structured content.
    • Defensive coding around undefined forEach calls when responses are
      malformed.
  • New CSS in customize.css for compact, readable error toasts
    (color-coded, monospace for codes/paths, line-broken for long messages).

Why

Today, when the API returns a Pydantic validation error or a structured
HTTP error, the WebUI either shows a generic message or dumps the raw
object to the console. End users have no signal of what's wrong, and
operators have to open the browser devtools.

This PR keeps the existing ShowToast API (no breaking change) and adds
a richer overlay path that:

  1. Plays nicely with FastAPI's default error envelope.
  2. Falls back gracefully for non-Pydantic errors.
  3. Is opt-in: existing call sites keep working unchanged.

Backward compatibility

  • No changes to existing ShowToast(message) callers.
  • No new endpoints or schema changes.
  • Pure frontend; the API layer is untouched.

Test plan

  • Existing WebUI flows still show toasts as before.
  • Trigger a Pydantic validation error (e.g. POST a malformed request
    to /libreapi/predefine/codec/{name}) and verify the new toast
    shows loc, msg and type clearly.
  • Trigger a {detail: "..."} error and verify the toast shows the
    detail string.
  • Trigger a network error (server down) and verify the fallback path.
  • Run with a long error string and confirm the duration scales.

Cherry-picked from a downstream deployment of LibreSBC where this
patch has been running in production for several months. Original
commit: 82a0f62.

…ions

- Add ShowAPIError function for better error display
- Enhance ShowToast with adaptive duration and HTML support
- Add protection against undefined array forEach errors
- Improve CSS styling for error messages
- Support Pydantic validation errors with structured display

This improves user experience by showing clear, structured error messages
instead of basic console errors, making debugging easier for users.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant