Frontend-Backend Integration Debug Skill

Degree of freedom: MIXED. Which side is wrong [HIGH freedom]; trace-both-sides probes [LOW freedom — run exactly].

Systematic approach to debugging frontend-backend integration issues by analyzing backend logs, production errors, and source code to identify root causes and fix both sides.

How to reason

1. Observe — status, payload, validation error, both logs
2. Interpret — FE omitted a field vs BE schema drifted vs auth/CORS
3. Classify — missing-param / type / 404 / 401 / 500 / CORS
4. Severity — 500 on a write path outranks a cosmetic 422 message

Worked example

Observe: FE GET /api/reports → 500; BE log ZodError: expected string, received undefined on year. Interpret: FE omitted year; BE schema required it with no default. Classify: missing-param — fix FE call and add a clear BE 422/default. Verify: same request returns 200 with the year bound; both sides updated.

Self-critique before reporting

• Both sides read — FE call and BE schema/logs, not one side guessed
• Contract named — status + payload field, not "they disagree"
• Fix matches class — 404 is not patched as a Zod default
• Right owner — single-layer crash → debug-error; proactive contract audit → audit-fe-api

Step 0: Auto-Detect Stack

Before debugging, discover the project's architecture.

0a. Detect Frontend Framework

Read package.json and look for:

0b. Detect Backend Framework

Glob: **/app/api/**/route.ts → Next.js App Router
Glob: **/pages/api/**/*.ts → Next.js Pages Router
Glob: **/server/api/**/*.ts → Nuxt server
Glob: **/src/routes/**/*.ts → Express/Hono/Fastify
Glob: **/src/app.ts or **/src/index.ts → Node backend entry
Glob: **/main.py or **/app.py → Python backend
Glob: **/main.go → Go backend

0c. Detect API Style and Validation

0d. Find Route and Controller Patterns

Grep: pattern "router\.(get|post|patch|put|delete)" glob "*.{ts,js}" — Express-style
Grep: pattern "app\.(get|post|patch|put|delete)" glob "*.{ts,js}" — Hono/Express
Grep: pattern "export (async function |const )(GET|POST|PATCH|PUT|DELETE)" glob "**/route.ts" — Next.js
Grep: pattern "defineEventHandler" glob "*.{ts,js}" — Nuxt/H3

0e. Record Discovery

STACK DISCOVERY:
- Frontend: [framework + version]
- Backend: [framework + version]
- API style: [REST / GraphQL / tRPC]
- Validation: [Zod / Joi / Yup / Pydantic / none]
- Route files: [pattern and locations]
- Controller files: [pattern and locations]
- Schema files: [pattern and locations]

Step 1: Research Debugging Patterns

1a. Firecrawl — Integration Debugging

Search the framework and validation library as written — recognizing the name is not knowing its current API or error shape.

firecrawl:firecrawl_search
{
 "query": "<FE_FRAMEWORK> <BE_FRAMEWORK> API integration debugging best practices [current year]",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

Additional targeted searches:

1b. Context7 — Framework Docs

context7:resolve-library-id
{
 "libraryName": "<VALIDATION_LIB>",
 "query": "error handling error messages custom errors"
}

Step 2: Gather Error Evidence

2a. Check Sentry for Production Errors

sentry:search_issues
{
 "organizationSlug": "<ORG_SLUG>",
 "query": "API integration errors 4xx 5xx validation from the last 7 days",
 "projectSlugOrId": "<PROJECT_SLUG>",
 "regionUrl": "<REGION_URL>",
 "limit": 25
}

If the project has separate FE and BE Sentry projects, check both:

• FE project: network errors, unhandled rejections from API calls
• BE project: validation errors, unhandled exceptions, 500s

2b. Read Backend Terminal Logs

Read the output of the terminal running the backend (npm run dev or equivalent) — in Cursor, terminals/*.txt; in Claude Code, the shell or log file you started it from.

Look for errors in the last 3-5 minutes:

• 4xx errors (400, 401, 403, 404, 422)
• 5xx errors (500, 502, 503)
• ZodError / ValidationError — validation failures
• AppError / custom error classes
• Stack traces
• Warning messages

2c. Categorize Errors Found

Step 3: Trace Errors to Source Code

3a. Map Errors to Endpoints

For each error found, use Grep to locate:

Frontend call:

Grep: pattern "<ERROR_ENDPOINT>" glob "*.{ts,tsx,js,jsx}"

Backend route:

Grep: pattern "<ERROR_ENDPOINT>" glob "*.{ts,js,py,go,rb}" — in backend source

Validation schema:

Grep: pattern "z\.object|z\.string|z\.number" in the controller/route file
SemanticSearch: "validation schema for <ENDPOINT>" target: [backend directory]

3b. Read the Full Chain

For each error, read the complete request chain:

1. Frontend call — Read the file making the API call (service, hook, or component)
2. API client config — Read the axios/fetch interceptor configuration
3. Backend route — Read the route handler
4. Backend controller — Read the controller/service logic
5. Validation schema — Read the Zod/Joi/Yup schema for the endpoint
6. Database query — Read the DB query (if the error is data-related)

3c. Verify Data State with Supabase MCP

If the error might be data-related:

supabase:execute_sql
{
 "query": "SELECT * FROM <TABLE> WHERE <CONDITION> LIMIT 5"
}

Check:

• Does the data the FE expects actually exist?
• Are enum values correct?
• Are foreign key relationships intact?
• Does the RLS policy allow access for this user?

Step 4: Generate Fix Recommendations

4a. Frontend Fixes

For each error, provide:

### Issue: [Endpoint] — [Error Type]

**Current FE Call:**
[show the actual code from Grep results]

**Correct FE Call:**
[show the fixed code]

**Why:** [explanation of required parameter/type/format]

**Files to Update:** [list specific files]

4b. Backend Enhancements

For each error, consider backend improvements — as recommendations in the report. Apply the fix for the contract failure at hand; the robustness enhancements ship only when the user asks, and every edit is surgical.

### Backend Enhancement: [Endpoint]

**Current Behavior:** Returns 500 with cryptic validation error

**Recommended Enhancement:**
- Add default value for optional params
- Add clear error message for required params
- Add type coercion where appropriate
- Return helpful 422 instead of 500

Example backend enhancement pattern:

// Before: bare schema, cryptic error on missing param
const schema = z.object({
 year: z.string(),
});

// After: defaults, coercion, clear errors
const schema = z.object({
 year: z.string({
 required_error: "year is required (format: YYYY)"
 }).default(() => new Date().getFullYear().toString()),
 page: z.coerce.number().default(1).int().positive(),
 limit: z.coerce.number().default(10).int().max(100),
});

Step 5: Backend Robustness Checklist

Input Validation

• All required params have clear error messages
• Default values for optional params with sensible defaults
• Type coercion where appropriate (string to number)
• Range validation (dates, numbers)
• Format validation (email, UUID, date strings)

Error Handling

• Catch and wrap database errors
• Provide actionable error messages (not "Internal Server Error")
• Log errors with context (userId, endpoint, params)
• Do not expose internal details to client (stack traces, SQL)

API Contract Consistency

• Response shape is consistent ({ data } or { error })
• Status codes are correct (200 success, 201 create, 204 delete)
• Pagination format is consistent across all list endpoints
• Date formats are consistent (ISO 8601)
• Error response shape is consistent

Output Template

## Frontend-Backend Integration Debug Report

**Analyzed:** [timestamp range]
**Frontend:** [framework]
**Backend:** [framework]
**API style:** [REST/GraphQL/tRPC]

---

### Production Errors (Sentry)

| Endpoint | Error | Events (7d) | Root Cause |
|----------|-------|-------------|------------|
| [endpoint] | [error msg] | [count] | [FE/BE/Data] |

---

### Backend Log Errors

| Endpoint | Method | Status | Error Type | Root Cause |
|----------|--------|--------|------------|------------|
| `/api/...` | GET | 500 | ZodError | Missing `year` param |
| `/api/...` | GET | 404 | Not Found | Endpoint not implemented |

---

### Critical Issues (Must Fix)

#### 1. [Endpoint] — [Status Code]
- **Error:** [error message]
- **Root Cause:** [explanation]
- **Frontend Fix:** [what FE needs to change, with code]
- **Backend Enhancement:** [optional BE improvement, with code]
- **Files:** FE: [path], BE: [path]

---

### Warnings (Should Fix)

#### 1. [Issue description]
- **Impact:** [what happens if not fixed]
- **Recommendation:** [how to fix]

---

### Backend Enhancements (Robustness)

#### 1. [Enhancement description]
- **Current:** [current behavior]
- **Recommended:** [better approach]
- **Benefit:** [why this helps]

---

### Research Findings Applied
- [Pattern from research]: [how it applies]
- [Best practice]: [gap identified]

---

### Summary Table

| Endpoint | Issue | Fix Required | Priority |
|----------|-------|--------------|----------|
| `/api/...` | Missing param | Frontend | HIGH |
| `/api/...` | No error handling | Both | MEDIUM |
| `/api/...` | Endpoint 404 | Remove or implement | LOW |

---

### Next Steps

1. [ ] Frontend fixes: [action items with files]
2. [ ] Backend enhancements: [action items with files]
3. [ ] Re-test: [verification steps]
4. [ ] Monitor: Check Sentry after deploy for regression

Common Patterns and Fixes

Pattern 1: Missing Query Parameter

Symptom: ZodError: expected string, received undefined

FE Fix: Add the missing parameter to the API call.

BE Fix: Add a default value or a clear error message.

Pattern 2: Endpoint Not Found (404)

Symptom: 404 /api/endpoint-name

Debug steps:

1. Grep for the endpoint path in backend route files
2. Check if the endpoint exists under a different name
3. Check API docs if available
4. Decide: remove FE call, fix typo, or implement endpoint

Pattern 3: Service Failure (500)

Symptom: 500 Internal Server Error with no useful message

Debug steps:

1. Read the backend controller for unhandled exceptions
2. Check if the service handles DB errors gracefully
3. Check RLS policies if using Supabase (data might be blocked)
4. Add try/catch with meaningful error responses

Pattern 4: CORS Error

Symptom: CORS policy: No 'Access-Control-Allow-Origin'

Debug steps:

1. Check backend CORS configuration
2. Verify the origin, methods, and headers allowed
3. Check if credentials mode matches between FE and BE

Pattern 5: Duplicate / Stale Requests

Symptom: Same API called multiple times, or stale data shown

Debug steps:

1. Check if TanStack Query / SWR staleTime is configured
2. Check if cache invalidation happens after mutations
3. Check if the queryKey is correct and unique
4. Check for component re-mount causing refetch

Integration with Other Skills

• audit-fe-api: Proactive audit from FE code perspective (run first).
• debug-sentry-monitor: Triage and fix Sentry errors from production.
• audit-db-schema: Verify DB schema matches API expectations.