Sentry Error Boundary with Offline Queue and Network-Aware Retry

[JamesEjembi]

Problem Statement / Feature Objective

Uncaught React errors, WebSocket connection drops, and API 5xx responses are reported to Sentry but lost when the device is offline. Errors also trigger repetitive alerts for transient failures. A Sentry error boundary must queue errors locally during offline periods and replays them on connectivity restore, with network-aware deduplication and backoff.

---

Technical Invariants & Bounds

• Offline queue capacity: 500 error records before LRU eviction
• Retry backoff: exponential, starting at 1 s, doubling, max 60 s, reset after 10 min of uptime
• Deduplication window: same error + same component + same hash within 5 seconds → merge with counter
• Max retry attempts per error: 5; after that, drop silently (no infinite retry)
• Queue persisted in IndexedDB under store sentry/offlineQueue

---

Codebase Navigation Guide

• src/lib/sentry/sentryClient.ts — current Sentry.init() and captureException wrapper
• src/components/error/AppErrorBoundary.tsx — existing React error boundary
• src/hooks/useNetworkStatus.ts — existing hook exposing navigator.onLine + online/offline events
• src/lib/storage/idb.ts — IndexedDB helper for persistence
• src/pages/_app.tsx (or equivalent root) — where Sentry.init is called

---

Implementation Blueprint

1. Extend src/lib/sentry/sentryClient.ts with enqueueError(error, context) that checks navigator.onLine. If offline, stores the error in IndexedDB under sentry/offlineQueue with { timestamp, errorHash, componentStack, count: 1 }. If online, calls Sentry.captureException immediately.
2. Create processOfflineQueue() function that reads all queued errors, attempts Sentry.captureException for each, and deletes them on success. On failure, increments retry count and re-stores with updated backoff timestamp.
3. In AppErrorBoundary.tsx, override componentDidCatch to call enqueueError instead of directly calling Sentry. Render a fallback UI with a "Retry" button and an indicator of queued errors.
4. Subscribe to useNetworkStatuss

[OkeyAmy]

Hello Chief, I would like to work on this issue. I have 4 years of experience as an open source contributor

[grantfox-oss]

🦊 GrantFox — @OkeyAmy has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #53)
2. Your PR will be reviewed by the Lumina-etwork maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@OkeyAmy's PR #71 was approved and merged by @JamesEjembi.

🏆 @OkeyAmy: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (576 total points). Track your full progress on GrantFox.

👏 Great work, @OkeyAmy! Keep contributing to Lumina-etwork.