cloudflare-debug

CavellTopDev's avatarfrom CavellTopDev

Debugging patterns for Cloudflare Workers. Activates when troubleshooting errors, checking logs, or investigating production issues.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026
[Debugging]

When & Why to Use This Skill

This Claude skill provides a comprehensive diagnostic toolkit for Cloudflare Workers, designed to streamline the troubleshooting process. It offers expert guidance on monitoring real-time production logs using Wrangler, setting up local-to-remote debugging environments, and resolving common serverless pitfalls such as CORS errors, authentication failures, and database connection issues.

Use Cases

  • Real-time log analysis: Using 'wrangler tail' with advanced filters (status, method, search) to isolate production errors in live traffic.
  • Local development with remote bindings: Debugging code locally while connected to production KV, R2, or Hyperdrive resources to replicate environment-specific bugs.
  • Automated diagnostic sequences: Executing a step-by-step verification process to identify if a failure originates from the Worker, the database, or the authentication layer.
  • Common error resolution: Quickly fixing recurring patterns like 'ReferenceError', 'TypeError', and specific HTTP status codes (401, 404, 500) within the Cloudflare ecosystem.
  • API testing and validation: Using optimized curl commands to verify endpoint health, session token validity, and JSON payload handling.
namecloudflare-debug
descriptionDebugging patterns for Cloudflare Workers. Activates when troubleshooting errors, checking logs, or investigating production issues.

Cloudflare Workers Debugging

Real-Time Log Commands

# All logs with pretty formatting
npx wrangler tail pitchey-api-prod --format pretty

# Errors only (most useful)
npx wrangler tail pitchey-api-prod --status error

# Filter by endpoint path
npx wrangler tail pitchey-api-prod --search "/api/browse"
npx wrangler tail pitchey-api-prod --search "/api/ndas"
npx wrangler tail pitchey-api-prod --search "/api/auth"
npx wrangler tail pitchey-api-prod --search "/api/pitches"

# Filter by HTTP method
npx wrangler tail pitchey-api-prod --method POST
npx wrangler tail pitchey-api-prod --method GET

# Combined filters
npx wrangler tail pitchey-api-prod --status error --search "/api/auth"
npx wrangler tail pitchey-api-prod --method POST --search "/api/ndas"

Local Debugging with Breakpoints

# Start dev server with remote bindings (connects to real DB/R2/KV)
npx wrangler dev --remote

# Press 'd' to open Chrome DevTools
# - Set breakpoints in Sources tab
# - Inspect variables in Scope panel
# - Profile memory usage
# - Check network requests

Test Endpoints Directly

# Health check
curl https://pitchey-api-prod.ndlovucavelle.workers.dev/health

# GET with auth (copy session cookie from browser DevTools)
curl -X GET "https://pitchey-api-prod.ndlovucavelle.workers.dev/api/user" \
  -H "Cookie: better-auth.session_token=YOUR_TOKEN"

# POST with JSON body
curl -X POST "https://pitchey-api-prod.ndlovucavelle.workers.dev/api/pitches" \
  -H "Content-Type: application/json" \
  -H "Cookie: better-auth.session_token=YOUR_TOKEN" \
  -d '{"title": "Test Pitch", "description": "Testing"}'

# Test browse endpoints
curl "https://pitchey-api-prod.ndlovucavelle.workers.dev/api/browse?tab=trending&limit=4"
curl "https://pitchey-api-prod.ndlovucavelle.workers.dev/api/browse?tab=new&limit=4"

Common Error Patterns

ReferenceError: X is not defined

  • Check imports at top of file
  • Verify variable is in scope where used
  • Check if variable was renamed but not updated everywhere
  • Look for typos in variable names

TypeError: Cannot read property 'X' of undefined

  • Add null checks before accessing properties
  • Verify API response shape matches expectations
  • Check if async data loaded before access

500 Internal Server Error

npx wrangler tail pitchey-api-prod --status error --format pretty
# Look for stack trace - shows exact file and line number

401 Unauthorized

  • Better Auth uses cookies, NOT JWT headers
  • Ensure credentials: 'include' in frontend fetch
  • Check session hasn't expired
  • Verify cookie domain matches

404 Not Found

  • Check route is registered in Worker
  • Verify HTTP method matches (GET vs POST)
  • Check for typos in endpoint path

CORS Errors

  • Frontend must use credentials: 'include'
  • Worker must return Access-Control-Allow-Credentials: true
  • Origin must match exactly (including https://)

Database Connection Errors

  • Always use: postgres(env.HYPERDRIVE.connectionString)
  • Never use direct Neon URL or pooler URL with Hyperdrive
  • Check Neon dashboard for connection limit issues

Session/Auth Errors (Better Auth)

  • Uses cookies, NOT Authorization header
  • Session cookie name: better-auth.session_token
  • Must include credentials in fetch calls
  • Check cookie SameSite and Secure attributes

Quick Diagnostic Sequence

# 1. Check if Worker is responding
curl -I https://pitchey-api-prod.ndlovucavelle.workers.dev/health

# 2. Stream errors
npx wrangler tail pitchey-api-prod --status error --format pretty

# 3. Test specific endpoint
curl "https://pitchey-api-prod.ndlovucavelle.workers.dev/api/[endpoint]"

# 4. Check with auth if needed
# Get cookie from browser, test with curl

# 5. If still stuck, enable local debugging
npx wrangler dev --remote
# Press 'd' for DevTools