debug-fe-be-integration

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:

Signal	Framework
next	Next.js
nuxt	Nuxt
@remix-run/react	Remix
@sveltejs/kit	SvelteKit
vite + react	Vite React SPA
@angular/core	Angular

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

Signal	Technology
@trpc/server	tRPC (type-safe, no REST audit needed)
graphql or @apollo/server	GraphQL
zod in BE dependencies	Zod validation
joi in BE dependencies	Joi validation
yup in BE dependencies	Yup validation
class-validator	NestJS-style validation
pydantic	Python Pydantic 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:

Topic	Query
Validation errors	<VALIDATION_LIB> error handling API response best practices
CORS issues	<BE_FRAMEWORK> CORS configuration debugging
Type mismatches	TypeScript API type safety frontend backend shared types

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

Category	Log Pattern	Root Cause
Missing parameter	ZodError: expected string, received undefined	FE not sending required param
Wrong type	ZodError: invalid_type	FE sending wrong type
Endpoint not found	404 /api/...	FE calling non-existent endpoint
Auth error	401 Unauthorized	Missing or invalid token
Permission error	403 Forbidden	User lacks permission
Validation error	422 Unprocessable	Invalid request body
Server error	500 Internal	Backend bug
CORS error	CORS policy	Missing CORS configuration

---

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.