error-handling · git:20260401.56e571e · 2026-04-01 · sha256 849ac3029c4d76c1
error-handling git:20260401.56e571eA
Immutable. This exact content never changes and is served at /api/v1/blob/849ac3029c4d76c1.
---
description: Error boundaries, loading states, and server error handling
globs: ["**/app/**"]
---
# Error Handling and Loading States
## RULE 1: Every Data-Fetching Page Needs Sibling Files
EVERY page in `app/` router that does data fetching MUST have:
- `loading.tsx` (Suspense boundary — shown during streaming)
- `error.tsx` (Error boundary — must be `'use client'`)
`loading.tsx` template:
```tsx
export default function Loading() {
return (
<div className="flex items-center justify-center min-h-[200px]">
<div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary" />
</div>
)
}
```
`error.tsx` template:
```tsx
'use client'
export default function Error({
error,
reset
}: {
error: Error & { digest?: string }
reset: () => void
}) {
return (
<div className="flex flex-col items-center justify-center min-h-[200px] gap-4">
<h2 className="text-xl font-semibold">Something went wrong</h2>
<p className="text-muted-foreground">An unexpected error occurred.</p>
<button
onClick={reset}
className="px-4 py-2 bg-primary text-primary-foreground rounded-md"
>
Try again
</button>
</div>
)
}
```
## RULE 2: NEVER Expose Internal Errors to Clients
Server errors, database errors, and stack traces MUST stay server-side.
Return generic messages to the client. Log the real error.
✅ CORRECT:
```typescript
try {
const { data, error } = await supabase.from('posts').select()
if (error) throw error
return data
} catch (error) {
console.error('[POSTS_FETCH_ERROR]', error) // Detailed log server-side
return NextResponse.json(
{ error: 'Failed to fetch posts' }, // Generic message to client
{ status: 500 }
)
}
```
❌ WRONG:
```typescript
} catch (error) {
return NextResponse.json(
{ error: error.message }, // Leaks: "relation 'posts' does not exist"
{ status: 500 }
)
}
```
## RULE 3: Use ActionResponse for All Server Actions
Every Server Action MUST return a typed response — never throw.
```typescript
type ActionResponse<T = void> =
| { success: true; data: T }
| { success: false; error: string }
// Usage:
export async function createPost(input: unknown): Promise<ActionResponse<Post>> {
const supabase = await createClient()
const { data: { user } } = await supabase.auth.getUser()
if (!user) return { success: false, error: 'Unauthorized' }
const parsed = PostSchema.safeParse(input)
if (!parsed.success) return { success: false, error: 'Invalid input' }
const { data, error } = await supabase
.from('posts')
.insert({ ...parsed.data, user_id: user.id })
.select()
.single()
if (error) {
console.error('[CREATE_POST_ERROR]', error)
return { success: false, error: 'Failed to create post' }
}
revalidatePath('/dashboard')
return { success: true, data }
}
```
## RULE 4: Handle Supabase Errors Explicitly
NEVER ignore the `error` field from Supabase queries.
✅ CORRECT:
```typescript
const { data, error } = await supabase.from('posts').select()
if (error) {
console.error('[SUPABASE_ERROR]', error.message, error.code)
throw new Error('Database query failed')
}
// data is now safely typed as non-null
```
❌ WRONG:
```typescript
const { data } = await supabase.from('posts').select()
// data could be null if query failed — using it causes runtime crash
return data.map(post => post.title) // TypeError: Cannot read property 'map' of null
```