debug: Add ErrorBoundary component for better error handling

[KJ7LNW]

Context

Fixes: #5731

This PR adds an ErrorBoundary component to capture and display React errors that might otherwise cause the UI to go blank or crash.

Implementation

• Adds a React ErrorBoundary component that captures errors in the component tree
• Displays a user-friendly error message with the full stack trace
• Wraps the entire application to prevent complete UI crashes
• Provides clear instructions for users to report errors

May help troubleshoot the blank/gray screen issue reported in #2270.

Based on work from Kilo-Org/kilocode#843.

How to Test

1. Intentionally cause an error in a component (e.g., try to access a property of undefined)
2. Observe that instead of a blank screen, a helpful error message appears
3. Verify the error message contains the full stack trace for debugging

Get in Touch

Discord: KJ7LNW

---

Important

Introduces ErrorBoundary component for improved error handling with source maps, updates tests, translations, and build configurations.

• Error Handling:
  • Adds ErrorBoundary component in ErrorBoundary.tsx to capture and display errors with stack traces.
  • Wraps the entire app in App.tsx with ErrorBoundary to prevent UI crashes.
  • Integrates source map support for better error reporting in sourceMapInitializer.ts and sourceMapUtils.ts.
• Testing:
  • Adds tests for ErrorBoundary in ErrorBoundary.spec.tsx and App.spec.tsx.
  • Mocks ErrorBoundary in App.spec.tsx to test app behavior without actual errors.
• Localization:
  • Updates translation files in locales to include error boundary messages in multiple languages.
• Build and Configuration:
  • Updates vite.config.ts and sourcemapPlugin.ts to ensure source maps are included in builds.
  • Modifies esbuild.mjs to always generate source maps for error handling.

^{This description was created by for fac992d05916d0b772ab560639de5b8c2eaba2bc. You can customize this summary. It will automatically update as commits are pushed.}

[KJ7LNW]

Ok, manual installed it, run for less than 1h and gray box :(
I feel like it's the same pattern, I get the grey box every 1-2 h

@NightOwlCoder ,

Please try this build and see if you can get a stack trace:

• https://www.linuxglobal.com/out/roo/roo-cline-3.21.5-error-boundary-component.vsix

[daniel-lxs]

Hey @KJ7LNW, I like this idea!

I left a couple of minor suggestions, I think this will benefit a lot from internationalization.

[KJ7LNW]

@daniel-lxs , this may not be possible I have been fighting with it all day: the backtraces look good in F5 debug mode, but when you build the package you do not get stack traces because everything is squashed into .js files.

@cte do you have any idea what might allow the build to support "real" backtraces that reference .ts/.tsx files and not .js files like it does in F5 debug mode?

[KJ7LNW]

@cte nevermind I was able to get it working using stacktrace-js

[KJ7LNW]

@daniel-lxs @cte this works great in production builds:

• https://www.linuxglobal.com/out/roo/roo-cline-3.21.5-error-boundary-component.vsix

Then trigger "Test ErrorBoundary"

and you get this. Notice real .tsx line numbers! hopefully this will help troubleshoot the grey screen issue.

[KJ7LNW]

@NightOwlCoder, please try this build and see if you can get us a stack trace instead of the blank screen that you have been getting:

• https://www.linuxglobal.com/out/roo/roo-cline-3.21.5-error-boundary-component.vsix

[daniel-lxs]

Hey @KJ7LNW, I really like this implementation. Great work!

I just had a few questions for clarification:

1. What types of errors will trigger the error screen? Is it only for webview-related errors?
2. Will the error screen appear if the webview crashes entirely, or does your implementation prevent a full crash from happening in the first place?
3. Does this have any impact on the performance of the extension, even when no error occurs?

Looking forward to your thoughts.

[KJ7LNW]

Hey @KJ7LNW, I really like this implementation. Great work!

I just had a few questions for clarification:

1. What types of errors will trigger the error screen? Is it only for webview-related errors?

This is only for web view and catches anything that gets propagated to <ErrorBoundary>, which should basically be anything because it is the topmost component:

https://github.com/RooCodeInc/Roo-Code/blob/fac992d05916d0b772ab560639de5b8c2eaba2bc/webview-ui/src/App.tsx#L228-L237

2. Will the error screen appear if the webview crashes entirely, or does your implementation prevent a full crash from happening in the first place?

At the moment we do not have enough information about complete webview crashes (grey screens) to know if they are recoverable, so this is more about gathering information than fixing a problem.

3. Does this have any impact on the performance of the extension, even when no error occurs?

Good question I was not sure, so I asked Claude 4 Opus, which was the only model that was capable of orchestrating via Sonnet 4 to do this successfully:

Performance Impact of ErrorBoundary Implementation

When No Errors Occur

The ErrorBoundary has minimal performance impact during normal operation:

1. No Additional Renders: When no errors occur, ErrorBoundary simply renders its children without any additional processing:

   if (!this.state.error) {
       return this.props.children
   }

2. No Lifecycle Overhead: The error handling methods (componentDidCatch, getDerivedStateFromError) are only called when an error is thrown, not during normal rendering.

3. No Source Map Loading: The source map utilities and StackTrace.js are only loaded/executed when an error actually occurs, not preemptively.

Performance Characteristics

Negligible Impact:

• ErrorBoundary is a simple class component that adds one conditional check per render
• No hooks, effects, or subscriptions running during normal operation
• No memory overhead beyond the component instance itself

Initialization Impact (one-time):

• initializeSourceMaps() in App.tsx adds event listeners and preloads source maps
• This happens once on app startup, not on every render
• In production, it attempts to preload source maps which may add a few network requests at startup

Error Handling Performance:

• When an error occurs, there's additional processing for source map resolution
• This is acceptable since errors are exceptional cases where debugging info is more important than performance

Best Practices Maintained

Your component hierarchy is optimal:

<ErrorBoundary>  // Catches all errors below
  <ExtensionStateContextProvider>
    <TranslationProvider>
      <QueryClientProvider>
        <App />

This ensures:

• Single error boundary at the top level (no redundant boundaries)
• No performance penalty for error-free execution
• All child components are protected

Conclusion: The ErrorBoundary implementation has virtually no performance impact during normal operation. It only adds meaningful overhead when errors occur, which is exactly when you need the enhanced debugging capabilities.

[chrarnoldus]

What types of errors will trigger the error screen? Is it only for webview-related errors?

I think it's only errors that happen during React rendering.

[KJ7LNW]

rebased and ready to merge

[KJ7LNW]

fixed lint issue, rebased on v3.23.14

[KJ7LNW]

FYI, I've been running this debug PR on my desk, and it caught #5978 with good debug information:

This is my test build so the line numbers vary, but they do point out the problem within a few lines of exactly the problem at command-validation.ts:109.

Without the ErrorBoundary, Roo just goes blank!

Here is a copy paste of the message.

Please help us improve by reporting this error on our GitHub Issues page

Copy and paste the following error message to include it as part of your submission:

Error Stack:
Error: Bad substitution: BASH_
at s.indexOf (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/node_modules/.pnpm/[email protected]/node_modules/shell-quote/parse.js:128:11)
at string.slice (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/node_modules/.pnpm/[email protected]/node_modules/shell-quote/parse.js:189:11)
at matches.map(function (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/node_modules/.pnpm/[email protected]/node_modules/shell-quote/parse.js:89:16)
at exports (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/node_modules/.pnpm/[email protected]/node_modules/shell-quote/parse.js:207:14)
at parse (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/webview-ui/src/utils/command-validation.ts:109:16)
at command.includes("$ (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/webview-ui/src/utils/command-validation.ts:393:21)
at JSON.parse (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/webview-ui/src/components/chat/ChatView.tsx:926:10)
at isMcpToolAlwaysAllowed (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/webview-ui/src/components/chat/ChatView.tsx:1003:33)
Component Stack:

at ChatViewComponent (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/webview-ui/src/components/chat/ChatView.tsx:76:3)
at App (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/webview-ui/src/App.tsx:78:5)
at Provider2 (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/node_modules/.pnpm/@[email protected]_@[email protected][email protected]/node_modules/@radix-ui/react-context/dist/index.mjs:27:14)
at TooltipProvider$1 (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/node_modules/.pnpm/@[email protected]_@[email protected]_@[email protected]__@types+reac_99504aa956c623e0884a4e3cb215669a/node_modules/@radix-ui/react-tooltip/dist/index.mjs:29:4)
at QueryClientProvider (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/node_modules/.pnpm/@[email protected][email protected]/node_modules/@tanstack/react-query/build/modern/QueryClientProvider.js:20:2)
at TranslationProvider (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/webview-ui/src/i18n/TranslationContext.tsx:16:73)
at ExtensionStateContextProvider (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/webview-ui/src/context/ExtensionStateContext.tsx:162:89)
at ErrorBoundary (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/webview-ui/src/components/ErrorBoundary.tsx:18:2)
at I18nextWithTranslation (https://file+.vscode-resource.vscode-cdn.net/home/ewheeler/node_modules/.pnpm/[email protected][email protected][email protected][email protected][email protected][email protected][email protected]/node_modules/react-i18next/dist/es/withTranslation.js:6:4)
at AppWithProviders

[mrubens]

This looks great, thanks!