Add Error Boundaries for Graceful Runtime Error Recovery

[pragmaticAweds]

Context & Impact

The application has zero React Error Boundaries. When any component throws a runtime error — a failed contract call, an undefined property access, a rendering exception — the entire application crashes to a white screen. Users lose all context, unsaved form data, and must manually refresh the page.

Why this matters: In a financial application handling real token streams and distributions, an unrecoverable crash is unacceptable. A single error in the offramp flow or stream table shouldn't take down the entire dashboard. Error boundaries isolate failures to the component that caused them and display a meaningful fallback UI.

Scope

• Create a reusable ErrorBoundary component with customizable fallback UI
• Add a global error boundary wrapping the root layout
• Add granular error boundaries around critical feature modules: payment stream, distribution, offramp, and token balances
• Implement a user-friendly error fallback with a "Try Again" action
• Log caught errors to console in development and to a reporting service hook in production
• Add Next.js error.tsx files for route-level error handling

Implementation Guidelines

• Use React class component for error boundaries (functional components cannot catch render errors)
• Provide a fallback prop for custom fallback UI per boundary
• Include an onReset callback so users can retry without a full page refresh
• Add error.tsx files in each route group: (overview)/dashboard, (overview)/payment-stream, (overview)/distribution, (overview)/offramp, (overview)/history
• Keep fallback UI consistent with the existing design system (Tailwind + Radix)
• Do not catch errors in event handlers — those should be handled by try/catch in hooks

Acceptance Criteria

• A reusable ErrorBoundary component exists in src/components/ui/
• Root layout wraps children with a global error boundary
• Each major route has an error.tsx file for route-level error recovery
• Payment stream, distribution, offramp, and balance modules each have their own error boundary
• Fallback UI displays a user-friendly message with a "Try Again" button
• Clicking "Try Again" resets the error boundary and re-renders the component
• Errors are logged to the console in development mode
• A runtime error in one module does not crash the entire application

Getting Started

1. Create src/components/ui/error-boundary.tsx as a React class component
2. Add a fallback prop that accepts a React node or a render function receiving the error
3. Wrap the root layout children in src/app/layout.tsx with the global error boundary
4. Create error.tsx files in each route directory under src/app/(overview)/
5. Add module-level error boundaries in the dashboard layout around each feature section
6. Test by temporarily throwing an error in a component and verifying the fallback renders
7. Verify that other modules remain functional when one module errors

---

PR Submission Guide

This section applies to every PR for this issue. Follow it exactly.

Before You Start

• Pull the latest main branch: git checkout main && git pull origin main
• Create your feature branch from main: git checkout -b feat/<issue-number>-error-boundaries

While Working

• Make atomic commits — one concern per commit, each commit must build
• Use Conventional Commits: feat(scope): description, fix(scope): description
• Keep your branch up to date: git pull origin main --rebase regularly

Before Submitting the PR

• Pull latest main and rebase: git checkout main && git pull origin main && git checkout <your-branch> && git rebase main
• Ensure the build passes: pnpm build
• Ensure linting passes: pnpm lint
• Record a screen recording of your implementation showing the feature/fix working in the browser. Attach it to the PR.

PR Requirements

• Link this issue in your PR description using Closes #<issue-number>
• Fill out the full PR template — Summary, What Was Implemented, Implementation Details, How to Test
• Attach your screen recording demonstrating the implementation
• Request a review from a maintainer

PRs without a screen recording or without a linked issue will not be reviewed.

[Abdulazeem-code]

@Abdulazeem-code has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

I would like to work on this issue Sir. Thank you very much sir

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Abdulazeem-code to this issue.

[drips-wave]

Congratulations, @Abdulazeem-code! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on March 30, 2026.

🧑‍💻 @Abdulazeem-code: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊