Skip to content

feat(error-handling): add global error boundary for root layout crashes#179

Merged
mikewheeleer merged 3 commits into
Agentpay-Org:mainfrom
SudiptaPaul-31:security/error-handling-global-boundary
Jun 26, 2026
Merged

feat(error-handling): add global error boundary for root layout crashes#179
mikewheeleer merged 3 commits into
Agentpay-Org:mainfrom
SudiptaPaul-31:security/error-handling-global-boundary

Conversation

@SudiptaPaul-31

@SudiptaPaul-31 SudiptaPaul-31 commented Jun 25, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds src/app/global-error.tsx — the top-level error boundary Next.js requires to catch exceptions thrown inside the root layout itself (Header, Footer, ToastProvider in layout.tsx). Without this file, a root-layout crash produces an unstyled white screen with no recovery path.

closes #83

Problem

The app had a route-level src/app/error.tsx boundary, but no global-error.tsx. Any exception thrown in the root layout escaped all boundaries and gave the user an unrecoverable blank screen.

Changes

src/app/global-error.tsx (new)

  • "use client" component as required by Next.js
  • Renders its own <html>/<body> shell so it works without the failed layout chrome
  • role="alert" + aria-live="assertive" on <main> for immediate screen-reader announcement
  • Shows error.message with a safe fallback ("An unexpected error occurred.") when the message is empty
  • Shows error.digest as a Reference ID for support correlation — conditionally rendered only when present
  • No stack traces rendered — safe for production
  • Uses inline styles (not Tailwind) so the page renders correctly even if the CSS pipeline that powers the normal layout has failed
  • Logs the error via console.error on mount (drop-in point for an observability service like Sentry)
  • "Try again" button calls Next.js's reset() to attempt recovery

src/app/global-error.test.tsx (new)

19 tests across 6 suites — 100% coverage (statements, branches, functions, lines):

Suite What it covers
Rendering heading, message, fallback copy, button, role="alert", aria-live, id="main-content"
error.digest shown when present, hidden when absent or undefined
Reset interaction reset() called once on click, called again on repeat clicks
Production safety raw stack trace never appears in the DOM
Standalone shell <html> and <body> declared in source; no Header/Footer/ToastProvider dependency
Button focus ring outline applied on focus, removed on blur
Error logging console.error called on mount with the error

README.md (updated)

  • Added Error boundaries section documenting both the route-level (error.tsx) and global (global-error.tsx) boundaries, their responsibilities, and design decisions
  • Added global-error.tsx entry to the project structure tree

Test output

PASS src/app/global-error.test.tsx (6.611 s)

  GlobalError — rendering
    ✓ renders the heading
    ✓ renders the error message when one is provided
    ✓ renders fallback copy when error.message is empty
    ✓ renders a Try again button
    ✓ wraps content in an alert region with aria-live=assertive
    ✓ gives the alert region id=main-content for skip-link compatibility

  GlobalError — error.digest
    ✓ renders the digest when present
    ✓ does not render the digest section when digest is absent
    ✓ does not render the digest section when digest is undefined explicitly

  GlobalError — reset interaction
    ✓ calls reset once when Try again is clicked
    ✓ calls reset again on each subsequent click

  GlobalError — production safety
    ✓ does not render the error stack trace
    ✓ does not render any stack-like content even when error has a long stack

  GlobalError — standalone shell
    ✓ declares its own <html> element in source (Next.js contract)
    ✓ declares its own <body> element in source (Next.js contract)
    ✓ does not depend on Header, Footer, or ToastProvider being present

  GlobalError — button focus ring
    ✓ applies a blue outline when the button receives focus
    ✓ removes the outline when the button loses focus

  GlobalError — error logging
    ✓ logs the error via console.error on mount

Tests:  19 passed, 19 total

File              | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
global-error.tsx  |   100   |   100    |   100   |   100   |

Checklist

  • npm run lint — clean
  • npm run typecheck — clean
  • npm test (new file) — 19/19 pass, 100% coverage
  • No stack traces rendered in production
  • Renders standalone without root layout chrome
  • Accessible — role="alert", aria-live="assertive", keyboard-focusable reset button with visible focus ring
  • Only the 3 required files added/modified — no unrelated changes

@mikewheeleer

mikewheeleer commented Jun 26, 2026

Copy link
Copy Markdown
Contributor

great stuff — merging this 🙌

@mikewheeleer mikewheeleer merged commit 757be02 into Agentpay-Org:main Jun 26, 2026
1 check passed
@grantfox-oss grantfox-oss Bot mentioned this pull request Jun 26, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Add a global-error boundary for root-layout failures

2 participants

@SudiptaPaul-31 @mikewheeleer