## Problem
When the table editor showed a "Failed to load tables" or "Failed to
load schemas" error (for example, when the underlying database or API
gateway is unhealthy), there was no working way to restart the project
from that error state. Restarting only worked by navigating to Project
Settings.
## Fix
"Failed to load tables" goes through the existing `ErrorMatcher`
classification system, which only showed troubleshooting steps
(including a restart action) for connection-timeout errors. Added an
`ERROR_MAPPINGS` entry for the unclassified/generic API error case,
reusing the existing `RestartDatabaseTroubleshootingSection` and
`RestartProjectDialog` components already used for connection timeouts.
"Failed to load schemas" (in the shared `SchemaSelector`, used across
the table editor and several Database pages) only offered a retry. Added
a "Restart database" button next to it, wired to the same
`RestartProjectDialog`.
## How to test
- In the table editor, trigger a table-load failure that isn't a
connection timeout (any generic API error). The error card should now
show a "Try restarting your project" step with a working restart action.
- Open the schema selector while schemas fail to load (e.g. mock a 503
from the schemas query). A "Restart database" button should appear next
to "Reload schemas" and open the restart confirmation dialog.
-
`apps/studio/components/interfaces/ErrorHandling/ErrorMatcher.test.tsx`
and `apps/studio/components/ui/SchemaSelector.test.tsx` cover both
cases.
FE-4054
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added database restart guidance when schema loading fails.
* Added options to reload schemas or restart the database, including a
confirmation prompt.
* Added troubleshooting guidance for unclassified table-loading errors.
* **Bug Fixes**
* Improved error handling by displaying relevant fallback guidance for
unknown errors while preserving classified troubleshooting instructions.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
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
Jordi Enric