---

name: api-error-debugger description: Debug API 500 errors and unexpected responses. Use when mobile apps get server errors, when API returns wrong data, or when investigating failed requests. Checks server logs, common error patterns, and Prisma query issues. allowed-tools: Read, Grep, Bash, Glob

API Error Debugger

Purpose

Quickly diagnose and fix API errors when mobile apps receive 500 errors, unexpected responses, or failed requests.

Quick Diagnosis Flow

1. Identify the Failing Endpoint

From mobile error logs, find the endpoint:

Copy# Android logs
~/Library/Android/sdk/platform-tools/adb logcat -d -t 100 | grep -E "(HTTP|api|error|Error)"

# iOS - check Xcode console or:
xcrun simctl spawn booted log show --last 5m --predicate 'subsystem == "com.constructionpro.app"'

2. Check Server Logs

If running locally:

Copy# Check Next.js dev server output for errors
# Look for stack traces and Prisma errors

3. Test Endpoint Directly

Copy# Replace TOKEN with valid JWT
curl -X GET "http://localhost:3000/api/[endpoint]" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" | jq

Common Error Patterns

Pattern 1: Prisma Field Not Found

Error: Unknown arg 'fieldName' in where.fieldName

Cause: Schema changed but client not regenerated

Fix:

Copycd apps/web
npx prisma db push
# Restart dev server

Pattern 2: Missing Required Field in Response

Error: Fields [X, Y] are required for type...

Cause: API not returning all fields Android/iOS model requires

Debug:

Copy# Find the Android model
grep -A 20 "data class [ModelName]" apps/android/**/model/*.kt

# Compare to API response
curl -s "http://localhost:3000/api/[endpoint]" -H "Authorization: Bearer $TOKEN" | jq

Fix: Add missing fields to API response

Pattern 3: JSON Parse Error (Array vs Object)

Error: Expected start of object '{', but had '['

Cause: API returns raw array, mobile expects wrapped object

Debug:

Copy# Check what API returns
curl -s "http://localhost:3000/api/[endpoint]" -H "Authorization: Bearer $TOKEN" | jq 'type'
# Returns "array" but should be "object"

Fix: Wrap array in object:

Copy// Before
return NextResponse.json(items)

// After
return NextResponse.json({ items, total: items.length, page: 1, pageSize: items.length })

Pattern 4: Authentication Error

Error: 401 Unauthorized or Invalid token

Debug:

Copy# Check if token is being sent
# Android - add logging to ApiService
# iOS - check network interceptor

# Verify token manually
curl -X GET "http://localhost:3000/api/auth/me" \
  -H "Authorization: Bearer $TOKEN"

Pattern 5: Prisma Relation Error

Error: Cannot read property 'X' of null

Cause: Relation not included in query or null relation accessed

Debug:

Copy# Find the Prisma query
grep -A 20 "prisma\.[model]\.find" apps/web/src/app/api/[endpoint]/route.ts

Fix: Add include or handle null:

Copy// Add include
const result = await prisma.model.findMany({
  include: { relation: true }
})

// Or handle null
return {
  relationField: item.relation?.field ?? null
}

Pattern 6: Type Mismatch

Error: Cannot deserialize or type coercion errors

Cause: API returns different type than mobile expects

Common mismatches:

• Date objects vs ISO strings
• Numbers as strings
• snake_case vs camelCase

Fix:

Copy// Serialize dates
createdAt: item.createdAt.toISOString()

// Ensure numbers
count: Number(item.count)

// Use camelCase
projectId: item.project_id  // Transform from snake_case

Debug Commands

Find API Route

Copy# Find route file for endpoint
find apps/web/src/app/api -name "route.ts" | xargs grep -l "[endpoint-keyword]"

Check Route Implementation

Copy# Read the route file
cat apps/web/src/app/api/[resource]/route.ts

Find Related Models

Copy# Prisma schema
grep -A 30 "model [ModelName]" apps/web/prisma/schema.prisma

# Android model
grep -A 30 "data class [ModelName]" apps/android/**/model/*.kt

# iOS model
grep -A 30 "struct [ModelName]" apps/ios/**/Models/*.swift

Test with Mock Data

Copy# POST with test data
curl -X POST "http://localhost:3000/api/[endpoint]" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"field": "value"}'

Checklist for Debugging

When investigating an API error:

• Identify exact endpoint and HTTP method
• Get the full error message from mobile logs
• Test endpoint directly with curl
• Compare API response structure to mobile model
• Check if all required fields are present
• Verify field types match (dates, numbers, etc.)
• Check for snake_case vs camelCase issues
• Verify authentication token is valid
• Check Prisma query includes all relations
• Ensure response wrapper format is correct

Quick Fixes