Studio Error Handling Agent Skill
Error display and troubleshooting pattern for Supabase Studio. Use when showing a failed API request or query error in the UI (AlertError, toast, inline message), adding troubleshooting steps for a new error type, or wiring up the AI assistant debug button from an error state.
Install
one command, takes just this skill from the repositorynpx skills add https://github.com/supabase/supabase --skill studio-error-handlingThe instruction itself
5 sections, as written by the authorStudio Error Handling Pattern
Full docs and code examples: apps/studio/components/interfaces/ErrorHandling/README.md
How it works
Classification happens in the data layer: handleError in data/fetchers.ts tests the error message against ERROR_PATTERNS and throws the matching error subclass (e.g. ConnectionTimeoutError extends ResponseError). The component (ErrorMatcher) reads errorType from the instance and does an O(1) lookup — it never does regex matching.
handleError() → throws ConnectionTimeoutError → React Query catches → ErrorMatcher reads errorType → renders troubleshooting
Key files
| File | Purpose |
| ------------------------------------- | ---------------------------------------------------------------- |
| data/error-patterns.ts | Array of { pattern, ErrorClass } — the regex lives here |
| types/api-errors.ts | Error classes, KnownErrorType union, ClassifiedError type |
| ErrorMatcher.tsx | Component — reads errorType, looks up mapping, renders |
| error-mappings.tsx | Record<KnownErrorType, { id, Troubleshooting: ComponentType }> |
| errorMappings/ConnectionTimeout.tsx | Reference troubleshooting component |
| TroubleshootingSections.tsx | Reusable accordion section components |
| TroubleshootingAccordion.tsx | Accordion wrapper with telemetry |
Usage
Pass the full error object from React Query — not error.message:
{
isError && (
<ErrorMatcher title="Failed to load tables" error={error} supportFormParams={{ projectRef }} />
)
}
What NOT to do
- Do not pass
error.messagetoErrorMatcher— pass the fullerrorobject so the class is preserved. - Do not put regex patterns in
error-mappings.tsx— they belong indata/error-patterns.ts. - Do not use
Object.assignto stamperrorType— throw a proper subclass instead. - Do not pass a raw URL string for support — use
supportFormParams={{ projectRef }}. - Do not put the page title inside the error mapping — it belongs on the
<ErrorMatcher>caller. - Do not add callback props (
onDebugWithAI,onRestartProject) to troubleshooting components — use hooks inside them instead.
Other skills for the same job
different authors, same section of the catalogue
Unified Python interface to 40+ bioinformatics services. Use when querying multiple databases (UniProt, KEGG, ChEMBL, Reactome) in a single workflow with consistent API. Best for cross-database analysis, ID mapping across services. For quick single-database lookups use gget; for sequence/file manipulation use biopython.
Python library for working with geospatial vector data including shapefiles, GeoJSON, and GeoPackage files. Use when working with geographic data for spatial analysis, geometric operations, coordinate transformations, spatial joins, overlay operations, choropleth mapping, or any task involving reading/writing/analyzing vector geographic data. Supports PostGIS databases, interactive maps, and integration with matplotlib/folium/cartopy. Use for tasks like buffer analysis, spatial joins between datasets, dissolving boundaries, clipping data, calculating areas/distances, reprojecting coordinate systems, creating maps, or converting between spatial file formats.
Fast CLI/Python queries to 20+ bioinformatics databases. Use for quick lookups: gene info, BLAST searches, AlphaFold structures, enrichment analysis. Best for interactive exploration, simple queries. For batch processing or advanced BLAST use biopython; for multi-database Python workflows use bioservices.
Direct REST API access to UniProt. Protein searches, FASTA retrieval, ID mapping, Swiss-Prot/TrEMBL. For Python workflows with multiple databases, prefer bioservices (unified interface to 40+ services). Use this for direct HTTP/REST work or UniProt-specific control.
Direct REST API access to UniProt. Protein searches, FASTA retrieval, ID mapping, Swiss-Prot/TrEMBL. For Python workflows with multiple databases, prefer bioservices (unified interface to 40+ services). Use this for direct HTTP/REST work or UniProt-specific control.
BullMQ expert for Redis-backed job queues, background processing, and reliable async execution in Node.js/TypeScript applications. Use when: bullmq, bull queue, redis queue, background job, job queue.
Create custom external web service APIs for Moodle LMS. Use when implementing web services for course management, user tracking, quiz operations, or custom plugin functionality. Covers parameter validation, database operations, error handling, service registration, and Moodle coding standards.
Python library for working with geospatial vector data including shapefiles, GeoJSON, and GeoPackage files. Use when working with geographic data for spatial analysis, geometric operations, coordinate transformations, spatial joins, overlay operations, choropleth mapping, or any task involving reading/writing/analyzing vector geographic data. Supports PostGIS databases, interactive maps, and integration with matplotlib/folium/cartopy. Use for tasks like buffer analysis, spatial joins between datasets, dissolving boundaries, clipping data, calculating areas/distances, reprojecting coordinate systems, creating maps, or converting between spatial file formats.
How to use it
Take supabase/studio-error-handling from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.