feat: improve error handling for unprocessable state deltas

Closed
TI
4mo ago
+99-17

Summary

Improves error handling when the backend sends state deltas that the frontend cannot process, addressing issue #6019.

Changes

Frontend (reflex/.templates/web/utils/state.js)

  • Added try-catch wrapper around event handler
  • Validates that dispatch[substate] exists before calling
  • Emits client_error event back to backend with actionable error messages
  • Stops processing further updates on error to prevent cascading failures

Backend (reflex/app.py)

  • Added on_client_error() handler to receive and log frontend errors in terminal
  • Added debug logging in emit_update() to show which substates are being sent
  • Provides actionable error messages (rebuild frontend, check api_url)

Documentation (reflex/state.py)

  • Enhanced StateUpdate class docstring to explain error handling behavior
  • Documents common causes of frontend/backend mismatch

Impact

  • ✅ Frontend errors now appear in backend terminal logs (where devs look first)
  • ✅ Clear, actionable error messages guide users to solutions
  • ✅ Prevents silent failures and broken-looking apps
  • ✅ Better debugging with substate logging

Testing

  • All 3540 unit tests pass
  • No breaking changes
  • Backward compatible

Fixes #6019