When the dashboard hits a DB connection timeout, users currently see a
raw error message with no
path forward. This PR adds an inline troubleshooting system that detects
known error types and
surfaces contextual next steps — restart the DB, read the docs, or debug
with AI.
## Changes
- New ErrorDisplay component (packages/ui-patterns) — styled error card
with a title, monospace error
block, optional troubleshooting slot, and a "Contact support" link that
always renders. Accepts
typed supportFormParams to pre-fill the support form.
- Error classification in handleError (data/fetchers.ts) — on every API
error, the message is tested
against ERROR_PATTERNS. If matched, handleError throws a typed subclass
(ConnectionTimeoutError
extends ResponseError) instead of a plain ResponseError. Stack traces
now show the exact error
class. All existing instanceof ResponseError checks continue to work.
- ErrorMatcher component — reads errorType from the thrown class
instance, does an O(1) lookup into
ERROR_MAPPINGS, and renders the matching troubleshooting accordion as
children of ErrorDisplay.
Falls back to plain ErrorDisplay for unclassified errors.
- Connection timeout mapping — first error type wired up, with three
troubleshooting steps: restart
the database, link to the docs, and "Debug with AI" (opens the AI
assistant sidebar with a
pre-filled prompt).
- Telemetry — three new typed events track when the troubleshooter is
shown, when accordion steps are
toggled, and which CTAs are clicked.
## Adding a new error type
1. Add a class to types/api-errors.ts
2. Add { pattern, ErrorClass } to data/error-patterns.ts
3. Create a troubleshooting component in errorMappings/
4. Add an entry to error-mappings.tsx
Sentry was flooded with un-actionable events: browser extension errors,
network blips, React hydration
noise from DOM-manipulating extensions, and CriticalError issues that
were impossible to route because
they grouped by message string rather than type. This made it hard to
spot real regressions.
## Changes:
- Improved client-side Sentry signal quality in
apps/studio/instrumentation-client.ts by replacing
custom third-party stack filtering with
Sentry.thirdPartyErrorFilterIntegration, plus stricter
allowUrls filtering for Supabase/app frames.
- Added build-time Sentry bundle annotation in
apps/studio/next.config.js via
unstable_sentryWebpackPluginOptions.applicationKey = 'supabase-studio'
to support reliable third-party
frame filtering.
- Expanded and reorganized ignoreErrors rules across client/server/edge
Sentry configs to suppress known
non-actionable noise (Next.js navigation internals, network/transient
chunk failures, extension/DOM-
manipulation noise, hydration-noise patterns).
- Refactored critical error reporting in
apps/studio/lib/error-reporting.ts from captureMessage to
captureException with scoped tags (critical=true, context=<action>) and
synthetic CriticalError
exceptions for better alerting/grouping.
- Updated tests in apps/studio/lib/error-reporting.test.ts to match the
new Sentry API usage (withScope
+ captureException) and assert on exception objects/tags behavior.
- 100% sampling (codeSampleRate = 1) for normal/useful errors.
- 1% sampling (codeSampleRate = 0.01) only for explicitly noisy classes:
- Failed to construct 'URL': Invalid URL
- Session error detected
- chunk-load failures (ChunkLoadError, Loading chunk ... failed, Loading
CSS chunk ... failed)
- Sent events are tagged with codeSampleRate so you can filter/segment
in Sentry dashboards.
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Charis