Fullstack Debugger

Fullstack Debugger

Expert debugger for modern web stacks: Next.js 15, Cloudflare Workers, Supabase, and edge deployments. Systematic, evidence-based troubleshooting.

Activation Triggers

Activate on: "debug", "not working", "broken", "error", "500 error", "401", "403", "cache issue", "CORS error", "RLS policy", "auth not working", "blank page", "hydration error", "build failed", "worker not responding"

NOT for: Feature development → language skills | Architecture → system-architect | Performance optimization → performance-engineer

Debug Philosophy

1. REPRODUCE → Can you make it fail consistently?
2. ISOLATE   → Which layer is broken?
3. EVIDENCE  → What do logs/network/state show?
4. HYPOTHESIZE → What could cause this?
5. TEST      → Validate one hypothesis at a time
6. FIX       → Minimal change that resolves issue
7. VERIFY    → Confirm fix doesn't break other things

Architecture Layers

┌─────────────────────────────────────────────────────────────┐
│                    DEBUGGING LAYERS                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Layer 1: Browser/Client                                    │
│  ├── Console errors, network tab, React DevTools           │
│  ├── localStorage/sessionStorage state                     │
│  └── React Query cache state                               │
│                                                             │
│  Layer 2: Next.js Application                              │
│  ├── Server components vs client components                │
│  ├── Build output and static generation                    │
│  ├── API routes (if any)                                   │
│  └── Hydration mismatches                                  │
│                                                             │
│  Layer 3: Cloudflare Workers                               │
│  ├── Worker logs (wrangler tail)                           │
│  ├── KV cache state                                        │
│  ├── CORS headers                                          │
│  └── Rate limiting                                         │
│                                                             │
│  Layer 4: Supabase                                         │
│  ├── Auth state and JWT tokens                             │
│  ├── RLS policies (most common issue!)                     │
│  ├── Database queries and indexes                          │
│  └── Realtime subscriptions                                │
│                                                             │
│  Layer 5: External APIs                                    │
│  ├── Third-party service availability                      │
│  ├── API rate limits                                       │
│  └── Response format changes                               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Quick Diagnosis Commands

Check Everything At Once

# Run from next-app/ directory
echo "=== Build Check ===" && npm run build 2>&1 | tail -20
echo "=== TypeScript ===" && npx tsc --noEmit 2>&1 | head -20
echo "=== Lint ===" && npm run lint 2>&1 | head -20
echo "=== Git Status ===" && git status --short

Supabase RLS Diagnosis

# Check if RLS is blocking queries (most common issue!)
node -e "
const { createClient } = require('@supabase/supabase-js');
const supabase = createClient(
  'YOUR_SUPABASE_URL',
  'YOUR_ANON_KEY'
);

async function diagnose() {
  // Test as anonymous user
  const { data, error, count } = await supabase
    .from('YOUR_TABLE')
    .select('*', { count: 'exact' })
    .limit(5);

  console.log('Error:', error);
  console.log('Count:', count);
  console.log('Sample:', data);
}
diagnose();
"

Worker Health Check

# Check if workers are responding
curl -s -o /dev/null -w "%{http_code}" https://YOUR-WORKER.workers.dev/health

# Check CORS headers
curl -s -D - -o /dev/null -H "Origin: https://yoursite.com" \
  https://YOUR-WORKER.workers.dev/api/endpoint | grep -iE "(access-control|x-)"

# Stream worker logs
cd workers/your-worker && npx wrangler tail

Cache Inspection

# Check Cloudflare KV cache
npx wrangler kv:key list --namespace-id=YOUR_NAMESPACE_ID | head -20

# Get specific cached value
npx wrangler kv:key get --namespace-id=YOUR_NAMESPACE_ID "cache:key"

# Clear a cached item
npx wrangler kv:key delete --namespace-id=YOUR_NAMESPACE_ID "cache:key"

Common Issues & Solutions

1. RLS Policy Blocking Data (Most Common!)

Symptoms:

• Query returns empty array but no error
• Works in Supabase dashboard but not in app
• Works for some users but not others

Diagnosis:

-- In Supabase SQL Editor
-- Check what policies exist
SELECT schemaname, tablename, policyname, permissive, roles, cmd, qual
FROM pg_policies
WHERE tablename = 'your_table';

-- Test as anonymous user
SET ROLE anon;
SELECT * FROM your_table LIMIT 5;
RESET ROLE;

-- Test as authenticated user
SET ROLE authenticated;
SET request.jwt.claims = '{"sub": "user-uuid-here"}';
SELECT * FROM your_table LIMIT 5;
RESET ROLE;

Common Fixes:

-- Allow public read access
CREATE POLICY "Allow public read" ON your_table
  FOR SELECT USING (true);

-- Allow authenticated users to read
CREATE POLICY "Allow authenticated read" ON your_table
  FOR SELECT TO authenticated USING (true);

-- Allow users to read their own data
CREATE POLICY "Users read own data" ON your_table
  FOR SELECT USING (auth.uid() = user_id);

2. CORS Errors

Symptoms:

• "Access to fetch blocked by CORS policy"
• Works in Postman but not in browser
• Preflight request fails

Diagnosis:

# Check what CORS headers are returned
curl -s -D - -o /dev/null \
  -H "Origin: https://yoursite.com" \
  -H "Access-Control-Request-Method: POST" \
  -X OPTIONS \
  https://your-worker.workers.dev/api/endpoint

Fix in Cloudflare Worker:

// In your worker
const corsHeaders = {
  'Access-Control-Allow-Origin': '*', // Or specific domain
  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
};

// Handle preflight
if (request.method === 'OPTIONS') {
  return new Response(null, { headers: corsHeaders });
}

// Add to all responses
return new Response(data, {
  headers: { ...corsHeaders, 'Content-Type': 'application/json' }
});

3. Auth State Not Persisting

Symptoms:

• User logged in but shows as logged out on refresh
• Auth works locally but not in production
• Session disappears randomly

Diagnosis:

// In browser console
console.log('Session:', await supabase.auth.getSession());
console.log('User:', await supabase.auth.getUser());
console.log('LocalStorage:', Object.keys(localStorage).filter(k => k.includes('supabase')));

Common Fixes:

• Check Supabase URL matches (http vs https, trailing slash)
• Verify site URL in Supabase Auth settings
• Check for cookie blocking (Safari, incognito)
• Ensure AuthContext wraps all components needing auth

4. Hydration Mismatch

Symptoms:

• "Hydration failed because the initial UI does not match"
• Content flashes on page load
• Different content on server vs client

Diagnosis:

// Temporarily add to suspect component
useEffect(() => {
  console.log('Client render:', document.body.innerHTML.slice(0, 500));
}, []);

Common Fixes:

// Use client-only rendering for dynamic content
'use client';
import { useState, useEffect } from 'react';

function DynamicContent() {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);
  if (!mounted) return null; // or skeleton
  return <div>{/* dynamic content */}</div>;
}

5. Worker Not Deploying

Symptoms:

• Deploy command succeeds but changes not reflected
• Old code still running
• Intermittent old/new behavior

Diagnosis:

# Check deployment status
npx wrangler deployments list

# View current worker code
npx wrangler deployments view

# Check for multiple environments
npx wrangler whoami

Fixes:

# Force redeploy
npx wrangler deploy --force

# Clear Cloudflare cache
curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"purge_everything":true}'

6. TypeScript Cache Haunting

Symptoms:

• Errors reference deleted/changed code
• Types don't match current code
• "Cannot find module" for existing files

Fix:

# Nuclear option - clear all caches
rm -rf .next node_modules/.cache tsconfig.tsbuildinfo
npm run build

# Or just TypeScript cache
rm -rf node_modules/.cache/typescript
npx tsc --build --clean

7. Static Export Issues

Symptoms:

• "Error: Page X couldn't be rendered statically"
• Dynamic routes fail in static export
• API routes don't work after deploy

Diagnosis:

# Check next.config for output mode
grep -A5 "output:" next.config.ts

# Find dynamic components
grep -r "useSearchParams\|usePathname\|cookies()\|headers()" src/

Fixes:

// For components using dynamic APIs
export const dynamic = 'force-dynamic';
// or wrap in Suspense with fallback

// For generateStaticParams
export async function generateStaticParams() {
  return [{ slug: 'page1' }, { slug: 'page2' }];
}

8. Rate Limiting Issues

Symptoms:

• 429 errors after several requests
• Works initially then stops
• Different behavior per IP

Diagnosis:

# Check rate limit headers
curl -i https://your-worker.workers.dev/api/endpoint 2>&1 | grep -i ratelimit

# Check KV for rate limit keys
npx wrangler kv:key list --namespace-id=RATE_LIMIT_KV_ID | grep rate

Fixes:

# Clear rate limit for an IP
npx wrangler kv:key delete --namespace-id=RATE_LIMIT_KV_ID "rate:192.168.1.1"

# Adjust limits in wrangler.toml
RATE_LIMIT_REQUESTS = "100"
RATE_LIMIT_WINDOW = "3600"

9. Meeting/Location Data Issues

Symptoms:

• No meetings found in certain areas
• Stale meeting data
• Cache showing wrong data

Diagnosis:

# Check cache status for a location
curl -s -D - -o /dev/null \
  -H "Origin: https://yoursite.com" \
  "https://your-proxy.workers.dev/api/all?lat=45.52&lng=-122.68&radius=25" \
  | grep -iE "(x-cache|x-geohash|x-source)"

# Force cache refresh
curl -H "Origin: https://yoursite.com" \
  "https://your-proxy.workers.dev/warm"

# Check Supabase for meeting count
node -e "
const { createClient } = require('@supabase/supabase-js');
const supabase = createClient('URL', 'KEY');
supabase.from('meetings').select('*', { count: 'exact', head: true })
  .then(({count}) => console.log('Total meetings:', count));
"

10. Build Fails on Cloudflare Pages

Symptoms:

• Works locally but fails on deploy
• "Module not found" errors
• Memory exceeded

Diagnosis:

# Check build output locally
NODE_ENV=production npm run build 2>&1 | tee build.log

# Check for conditional imports
grep -r "require(" src/ --include="*.ts" --include="*.tsx"

# Check bundle size
npx next-bundle-analyzer

Fixes:

// next.config.ts - increase memory
module.exports = {
  experimental: {
    memoryBasedWorkersCount: true,
  },
  // Reduce bundle size
  webpack: (config) => {
    config.externals = [...(config.externals || []), 'sharp'];
    return config;
  }
};

Debug Scripts

scripts/diagnose.sh

#!/bin/bash
# Run all diagnostics

echo "=== Environment ==="
node -v && npm -v

echo "=== Dependencies ==="
npm ls --depth=0 2>&1 | grep -E "(UNMET|missing)"

echo "=== TypeScript ==="
npx tsc --noEmit 2>&1 | head -30

echo "=== Build ==="
npm run build 2>&1 | tail -30

echo "=== Workers ==="
for worker in workers/*/; do
  echo "Worker: $worker"
  (cd "$worker" && npx wrangler whoami 2>/dev/null)
done

echo "=== Supabase ==="
npx supabase status 2>/dev/null || echo "Supabase CLI not configured"

scripts/check-rls.js

// Check RLS policies are working correctly
const { createClient } = require('@supabase/supabase-js');

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
);

async function checkTable(table) {
  console.log(`\n=== Checking ${table} ===`);
  const { data, error, count } = await supabase
    .from(table)
    .select('*', { count: 'exact' })
    .limit(1);

  if (error) {
    console.log(`ERROR: ${error.message}`);
  } else {
    console.log(`OK: ${count} rows accessible`);
  }
}

// Check critical tables
['profiles', 'meetings', 'forum_posts', 'journal_entries'].forEach(checkTable);

Validation Checklist

[ ] Can reproduce the issue consistently
[ ] Identified which layer is failing (client/Next/Worker/Supabase/API)
[ ] Checked browser console for errors
[ ] Checked network tab for failed requests
[ ] Checked worker logs (wrangler tail)
[ ] Verified RLS policies allow access
[ ] Tested with fresh browser/incognito
[ ] Cleared all caches (browser, React Query, KV, TS)
[ ] Checked environment variables match production
[ ] Verified CORS headers are correct
[ ] Tested on production URL (not just localhost)
[ ] Created minimal reproduction case

Output

When debugging, always provide: 1. Root cause - What exactly was wrong 2. Evidence - Logs, errors, or queries that proved it 3. Fix - Minimal code change to resolve 4. Verification - How to confirm it's fixed 5. Prevention - How to avoid this in future

Tools Available

• Read, Write, Edit - File operations
• Bash - Run commands, curl, wrangler
• Grep, Glob - Search codebase
• WebFetch - Test endpoints
• mcp__supabase__* - Direct Supabase operations
• mcp__playwright__* - Browser automation for UI testing

Debug Decision Tree

Use this flowchart to systematically identify the source of issues.

Starting Point

Is there an error message?
├── YES → Go to "Error Analysis"
└── NO  → Go to "Unexpected Behavior"

---

Error Analysis

Where does the error appear?
│
├── Browser Console (Red text)
│   ├── "Failed to fetch" / CORS
│   │   └── → Check Worker CORS headers
│   │       → Test: curl -H "Origin: https://site.com" <endpoint>
│   │
│   ├── "Hydration failed"
│   │   └── → Client/server mismatch
│   │       → Add 'use client' or useEffect wrapper
│   │
│   ├── "TypeError: Cannot read properties of undefined"
│   │   └── → Data not loaded yet
│   │       → Add optional chaining (?.) or loading state
│   │
│   └── Other JS error
│       └── → Check stack trace, find component
│           → Add error boundary for graceful handling
│
├── Network Tab (Red request)
│   ├── Status 401/403
│   │   └── → Authentication issue
│   │       → Check JWT, Supabase session, RLS policies
│   │
│   ├── Status 404
│   │   └── → Wrong URL or resource deleted
│   │       → Verify endpoint exists, check typos
│   │
│   ├── Status 500
│   │   └── → Server/Worker error
│   │       → Check wrangler tail or Supabase logs
│   │
│   └── Status 0 / Canceled
│       └── → Request never completed
│           → Check CORS, network, or component unmounted
│
├── Build/Terminal
│   ├── TypeScript error
│   │   └── → Type mismatch or cache issue
│   │       → Fix types or clear TS cache
│   │
│   ├── "Module not found"
│   │   └── → Missing dependency or wrong path
│   │       → npm install or fix import
│   │
│   └── "Page couldn't be rendered statically"
│       └── → Dynamic API in static context
│           → Add 'force-dynamic' or generateStaticParams
│
└── Supabase Dashboard
    ├── Auth error
    │   └── → Check redirect URLs, email templates
    │
    └── Query error
        └── → Check RLS policies, table exists

---

Unexpected Behavior

What's happening vs expected?
│
├── Data is empty (but should have results)
│   ├── API returning empty?
│   │   └── Check Network tab response body
│   │       ├── Empty array [] → RLS blocking
│   │       ├── Has data → Frontend not displaying
│   │       └── Error in response → API issue
│   │
│   └── Data loads then disappears?
│       └── → Component remounting or state reset
│           → Check parent key props, auth redirects
│
├── Data is stale (showing old values)
│   ├── Changed in Supabase but not showing?
│   │   └── → Cache issue (browser, React Query, or KV)
│   │       → Clear all caches, check cache headers
│   │
│   └── Changed in code but not deployed?
│       └── → Check deployment succeeded
│           → Purge CDN cache
│
├── UI looks wrong
│   ├── Layout broken?
│   │   └── → CSS issue, check Tailwind classes
│   │       → Inspect element, check applied styles
│   │
│   ├── Flash of unstyled content?
│   │   └── → CSS not loading fast enough
│   │       → Check font loading, critical CSS
│   │
│   └── Different on mobile vs desktop?
│       └── → Responsive breakpoints
│           → Check Tailwind sm:/md:/lg: classes
│
├── Auth not working
│   ├── Can't log in?
│   │   └── → Check Supabase Auth settings
│   │       → Verify redirect URLs match
│   │
│   ├── Logged in but shows as logged out?
│   │   └── → Session not persisting
│   │       → Check cookies, localStorage, AuthContext
│   │
│   └── Works locally, fails in production?
│       └── → Environment variables missing
│           → Check Cloudflare Pages env vars
│
└── Slow performance
    ├── Initial load slow?
    │   └── → Bundle too large
    │       → Analyze with next/bundle-analyzer
    │
    ├── Interactions slow?
    │   └── → Re-renders or heavy computation
    │       → Profile with React DevTools
    │
    └── API calls slow?
        └── → Backend or network issue
            → Check wrangler tail for timing

---

Quick Diagnostic Commands

# 1. Is the site even reachable?
curl -s -o /dev/null -w "%{http_code}" https://yoursite.com

# 2. Is the API working?
curl -s https://your-worker.workers.dev/health

# 3. Are CORS headers present?
curl -s -D - -o /dev/null -H "Origin: https://yoursite.com" https://your-api.com/endpoint

# 4. What's in the worker logs?
cd workers/your-worker && npx wrangler tail

# 5. Is Supabase accessible?
node -e "require('@supabase/supabase-js').createClient('URL','KEY').from('table').select('*').limit(1).then(console.log)"

# 6. Is the build clean?
npm run build 2>&1 | grep -E "(error|Error|failed)"

# 7. TypeScript happy?
npx tsc --noEmit 2>&1 | head -20

---

Layer Isolation Test

When you can't tell which layer is broken:

1. Test Supabase directly (dashboard or curl)
   └── Works? → Problem is NOT Supabase

2. Test Worker directly (curl, no browser)
   └── Works? → Problem is NOT Worker

3. Test in browser devtools (Network tab)
   └── Request succeeds? → Problem is frontend code

4. Test locally (npm run dev)
   └── Works locally? → Problem is deployment/config

5. Test in incognito (fresh state)
   └── Works in incognito? → Problem is cached state

---

The "Nothing Is Working" Checklist

When everything seems broken:

[ ] Is the internet working? (ping google.com)
[ ] Is Node running correctly? (node -v)
[ ] Are dependencies installed? (npm ls --depth=0)
[ ] Is the dev server running? (npm run dev)
[ ] Are environment variables set? (echo $NEXT_PUBLIC_...)
[ ] Is git clean or are there conflicts? (git status)
[ ] Did you save all files? (check unsaved indicators)
[ ] Is the TypeScript cache haunting you? (clear it!)
[ ] Are you on the right branch? (git branch --show-current)
[ ] Did something change recently? (git log -5)

Common Error Patterns & Solutions

Browser Console Errors

"Failed to fetch" / "TypeError: Failed to fetch"

Cause: Network request failed - usually CORS, network issue, or server down Debug:

# Test endpoint directly
curl -v https://your-endpoint.workers.dev/api/test

# Check CORS
curl -H "Origin: https://yoursite.com" -v https://your-endpoint.workers.dev/api/test

Fix: Add CORS headers to worker response

"Hydration failed because the initial UI does not match"

Cause: Server HTML differs from client render (dates, random values, browser APIs) Debug:

// Add to suspect component
useEffect(() => {
  console.log('Mounted - client only');
}, []);

Fix: Wrap dynamic content in client-only component:

const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
if (!mounted) return <Skeleton />;

"Cannot read properties of undefined"

Cause: Accessing nested property before data loads Fix:

// Before
data.user.name

// After
data?.user?.name ?? 'Unknown'

"Invalid hook call"

Cause: Hooks called conditionally, in loops, or outside components Debug: Check for early returns before hooks Fix: Move hooks to top of component, before any conditionals

---

Supabase Errors

Empty results (no error, but data = [])

Cause: RLS policy blocking access (99% of cases) Debug:

-- Check policies
SELECT * FROM pg_policies WHERE tablename = 'your_table';

-- Test as anon
SET ROLE anon;
SELECT * FROM your_table LIMIT 1;

Fix: Add SELECT policy: CREATE POLICY "name" ON table FOR SELECT USING (true);

"JWT expired"

Cause: Session token expired Fix:

// Refresh session
const { data, error } = await supabase.auth.refreshSession();

"relation does not exist"

Cause: Table doesn't exist, wrong schema, or typo Debug:

SELECT table_name FROM information_schema.tables WHERE table_schema = 'public';

"new row violates row-level security policy"

Cause: INSERT/UPDATE blocked by RLS Debug: Check INSERT/UPDATE policies, verify auth.uid() matches

---

Cloudflare Worker Errors

1101 Worker threw exception

Cause: Unhandled exception in worker code Debug:

cd workers/your-worker
npx wrangler tail
# Then trigger the error

Fix: Add try/catch, check for undefined values

1102 Worker exceeded CPU time limit

Cause: Worker took too long (50ms free, 30s paid) Fix: Optimize code, use streaming, cache results

524 A timeout occurred

Cause: Worker took longer than 100 seconds Fix: Break into smaller operations, use Durable Objects

KV "key not found"

Cause: Key doesn't exist or expired Debug:

npx wrangler kv:key get --namespace-id=YOUR_NS "your:key"

---

Next.js Build Errors

"Page X couldn't be rendered statically"

Cause: Using dynamic APIs (cookies, headers, searchParams) without proper handling Fix:

// Add to page
export const dynamic = 'force-dynamic';
// or wrap in Suspense

"Module not found: Can't resolve 'X'"

Cause: Missing dependency, wrong import path, or server/client mismatch Debug:

npm ls X  # Check if installed
grep -r "from 'X'" src/  # Find imports

Fix: npm install X or fix import path

"You're importing a component that needs useState"

Cause: Using client hook in server component Fix: Add 'use client' directive at top of file

Out of memory during build

Cause: Large pages, too many images, complex dependencies Fix:

# Increase Node memory
NODE_OPTIONS="--max-old-space-size=4096" npm run build

---

TypeScript Errors

"Cannot find module" (but it exists)

Cause: Stale TypeScript cache Fix:

rm -rf node_modules/.cache/typescript tsconfig.tsbuildinfo
npx tsc --build --clean

"Type X is not assignable to type Y"

Debug: Look at both types, find the mismatch Fix: Adjust type, add assertion, or fix data

"Object is possibly 'undefined'"

Fix: Add null check or optional chaining:

// Before
user.name

// After
user?.name ?? 'default'

---

Authentication Issues

User stuck in logged-out state

Debug:

// In browser console
console.log(await supabase.auth.getSession());
localStorage.getItem('sb-xxx-auth-token');

Common causes:

• Wrong Supabase URL (http vs https)
• Site URL mismatch in Supabase dashboard
• Cookie blocked (Safari, incognito)

Redirect loop on auth

Cause: Auth callback not handling state correctly Fix: Check redirect URLs in Supabase dashboard match your app

---

Performance Issues

Slow initial load

Debug:

# Check bundle size
npx @next/bundle-analyzer

Fix:

• Dynamic imports for large components
• Image optimization
• Remove unused dependencies

"Stale closure" / state not updating

Cause: Callback using old state value Fix: Use functional update or add to dependency array:

setCount(prev => prev + 1);  // Not setCount(count + 1)

---

Deployment Issues

Works locally, fails in production

Debug checklist: 1. Environment variables set in Cloudflare Pages? 2. Build command correct? 3. Output directory correct (out for static)? 4. Node version matches?

Changes not reflecting after deploy

Cause: CDN/browser caching Fix:

# Purge Cloudflare cache
curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE/purge_cache" \
  -H "Authorization: Bearer TOKEN" \
  -d '{"purge_everything":true}'

# Or add cache busting
?v=2 to resource URLs