The Complete Claude Code Debugging Workflow Guide: AI-Powered Error Diagnosis

# Step 1: Hypothesis — describe the symptom
> The checkout page shows a blank screen after clicking "Place Order".
> No errors in the console. Network tab shows a 200 response.
 
# Step 2: Verify — Claude Code suggests checks
# Check error boundaries, silent promise rejections, conditional null renders
 
# Step 3: Narrow — provide more context
> The response body from /api/checkout is: {"status": "success", "orderId": null}
> orderId is null — could that be the issue?
 
# Step 4: Claude Code traces orderId through your components

# Bad: just the error message
> TypeError: Cannot read properties of undefined (reading 'map')
 
# Good: full stack trace + what changed recently
> I'm getting this error when loading the blog list page:
> TypeError: Cannot read properties of undefined (reading 'map')
>     at BlogList (app/[locale]/blog/page.tsx:42:18)
>     at renderWithHooks (node_modules/react-dom/...)
> The page was working yesterday. I recently changed getPostsByLocale
> to add tag filtering.

# Unknown error
> I'm seeing this error and I don't understand it: [paste full error + stack trace]
 
# Error with context
> This error started after [describe recent change]: [paste error]
 
# Intermittent error
> This error happens about 30% of the time: [paste error]
> What could cause it to be intermittent?

> The dashboard page is crashing. It has 8 widgets.
> Comment out the bottom 4 widgets to check if the bug is in the top or bottom half.

git bisect start
git bisect bad          # current commit is broken
git bisect good abc123  # this older commit was working
# Git checks out a middle commit — test it, then: git bisect good/bad
# Repeat until git identifies the exact commit

> The blog search is broken — it was working at commit a1b2c3d.
> Use git bisect with `npm test -- --run search` to find the bad commit.

git bisect start && git bisect bad HEAD && git bisect good a1b2c3d
git bisect run npm test -- --run search

> Here are the last 50 lines of the server log when the error occurs:
> [paste logs]
> Identify the first error, any timing patterns, and which module is failing.

> Something broke after running npm update yesterday.
> Compare package-lock.json with the previous version and identify
> which packages changed. Check changelogs for breaking changes.

> Add debugging logs to the checkout flow. Use structured logging with
> timestamp, function name, sanitized parameters, and output/error.

// lib/debug.ts
const DEBUG = process.env.NODE_ENV === 'development'
 
export function debugLog(
  fn: string,
  action: 'enter' | 'exit' | 'error',
  data?: Record<string, unknown>
) {
  if (!DEBUG) return
  const prefix = { enter: '→', exit: '←', error: '✗' }[action]
  console.log(`[${new Date().toISOString()}] ${prefix} ${fn}`, data ?? '')
}
 
// Usage
export async function processCheckout(cart: Cart, user: User) {
  debugLog('processCheckout', 'enter', { cartItems: cart.items.length, userId: user.id })
  try {
    const order = await createOrder(cart, user)
    debugLog('processCheckout', 'exit', { orderId: order.id })
    return order
  } catch (error) {
    debugLog('processCheckout', 'error', {
      message: error instanceof Error ? error.message : 'Unknown error',
    })
    throw error
  }
}

export async function fetchPosts(locale: string, tag?: string) {
  const posts = await getPostsByLocale(locale)
  const filtered = tag ? posts.filter(p => p.tags.includes(tag)) : posts
 
  // Only log when results are unexpectedly empty
  if (filtered.length === 0 && posts.length > 0) {
    console.warn('[fetchPosts] Filter returned 0 results', {
      locale, tag, totalPosts: posts.length,
      availableTags: [...new Set(posts.flatMap(p => p.tags))],
    })
  }
  return filtered
}

> The dashboard is showing stale data. Add a fetch wrapper that logs all requests.

// lib/debug-fetch.ts
const originalFetch = globalThis.fetch
 
export function enableFetchDebugging() {
  globalThis.fetch = async (input, init) => {
    const url = typeof input === 'string' ? input : input.toString()
    console.group(`[Fetch] ${init?.method ?? 'GET'} ${url}`)
    try {
      const response = await originalFetch(input, init)
      console.log('Status:', response.status)
      console.groupEnd()
      return response
    } catch (error) {
      console.error('Fetch error:', error)
      console.groupEnd()
      throw error
    }
  }
}

> The shopping cart count doesn't update when I add items.
> Add state change logging to the CartProvider.

// context/CartContext.tsx
export function CartProvider({ children }: { children: React.ReactNode }) {
  const [cart, setCart] = useState<CartState>(initialState)
  const prevCartRef = useRef<CartState>(initialState)
 
  useEffect(() => {
    if (process.env.NODE_ENV === 'development') {
      const prev = prevCartRef.current
      console.log('[CartProvider] State changed:', {
        prevItems: prev.items.length,
        newItems: cart.items.length,
        added: cart.items.filter(i => !prev.items.find(p => p.id === i.id)),
        removed: prev.items.filter(i => !cart.items.find(c => c.id === i.id)),
      })
      prevCartRef.current = cart
    }
  }, [cart])
  // ... rest of provider
}

> Users sometimes see stale profile data after updating their profile.
> The update API returns 200, but the page still shows old data.
> This happens maybe 20% of the time. Could this be a race condition?

// Bug: race condition between update and refetch
async function handleProfileUpdate(data: ProfileData) {
  await updateProfile(data)
  router.refresh() // Doesn't wait for revalidation to complete
}
 
// Fix: optimistic update or wait for revalidation
async function handleProfileUpdate(data: ProfileData) {
  const updated = await updateProfile(data)
  setProfile(updated) // Optimistic update — immediate UI feedback
}

> Audit the API route handlers in app/api/ for unhandled promise rejections.
> Check for missing try/catch, .then() without .catch(), and un-awaited promises.

// Bug: fire-and-forget promise — errors silently swallowed
export async function POST(request: Request) {
  const data = await request.json()
  sendNotificationEmail(data.email, data.orderId) // Not awaited!
  return Response.json({ success: true })
}
 
// Fix: await or explicitly handle the error
export async function POST(request: Request) {
  const data = await request.json()
  sendNotificationEmail(data.email, data.orderId).catch(error => {
    console.error('[POST /api/order] Email failed:', error)
  })
  return Response.json({ success: true })
}

> The server becomes unresponsive for 2-3 seconds every minute.
> CPU spikes to 100%. Could something be blocking the event loop?

// Bug: synchronous file read in a request handler
export async function GET(request: Request) {
  const data = fs.readFileSync('/path/to/large-file.json', 'utf-8') // Blocks!
  return Response.json(JSON.parse(data))
}
 
// Fix: use async version
export async function GET(request: Request) {
  const data = await fs.promises.readFile('/path/to/large-file.json', 'utf-8')
  return Response.json(JSON.parse(data))
}

> The app works locally but fails in CI/staging with this error: [paste error]
> Walk me through the checklist: Node version? Env vars? Path case sensitivity?
> OS-specific behavior? Dependency version differences?

> The app crashes in production with "Invalid URL" but works locally.
> Check all environment variable usage and identify any that might
> be undefined in production.

// lib/env.ts — defensive environment variable access
export function getRequiredEnv(key: string): string {
  const value = process.env[key]
  if (!value) {
    throw new Error(`Missing required environment variable: ${key}`)
  }
  return value
}

// Bug: works on Mac (case-insensitive), fails on Linux
import { UserAvatar } from '@/components/userAvatar'
// Actual file: components/UserAvatar.tsx — fix: match exact case

> I'm getting "Cannot find module 'react-dom/client'" in CI
> but it works locally. Compare my local Node/npm versions with CI.

node -v          # Local: v22.x, CI: v18.x
npm -v           # Local: 10.x, CI: 9.x

{
  "engines": { "node": ">=20.0.0", "npm": ">=10.0.0" }
}

> Run a Lighthouse audit on the blog list page. Focus on LCP, CLS, and TBT.
> Suggest specific fixes for any metric below 90.

> The initial page load is 2.3MB of JavaScript.
> Analyze the bundle and identify the largest packages,
> lazy-loadable packages, and duplicate packages.

# Enable Next.js bundle analyzer
ANALYZE=true npm run build

> The bundle analysis shows:
> - lodash: 72KB (only using _.debounce)
> - moment: 230KB (only using format)
> - highlight.js: 180KB (loading all languages)
>
> Replace each with a lighter alternative or tree-shakeable import.

> The app's memory grows from 150MB to 800MB over 2 hours.
> Check for event listeners not cleaned up, intervals not cleared,
> and growing caches without eviction.

// Bug: event listener leak in React component
function SearchBar() {
  const [query, setQuery] = useState('')
 
  // Bug: new listener on every render, never removed
  useEffect(() => {
    window.addEventListener('keydown', handleKeyDown)
  }) // Missing dependency array
 
  // Fix: add cleanup and dependency array
  useEffect(() => {
    window.addEventListener('keydown', handleKeyDown)
    return () => window.removeEventListener('keydown', handleKeyDown)
  }, [])
}

// Bug: growing cache with no eviction
const cache = new Map<string, unknown>()
export async function getCachedData(key: string) {
  if (cache.has(key)) return cache.get(key)
  const data = await fetchData(key)
  cache.set(key, data) // Cache grows forever — use LRU cache instead
  return data
}

> The /api/posts endpoint takes 3-5 seconds to respond.
> Add query timing to identify which database query is slow.

// lib/db-debug.ts
export async function timedQuery<T>(name: string, queryFn: () => Promise<T>): Promise<T> {
  const start = performance.now()
  try {
    const result = await queryFn()
    const ms = performance.now() - start
    if (ms > 1000) console.warn(`[SLOW QUERY] ${name}: ${ms.toFixed(0)}ms`)
    return result
  } catch (error) {
    console.error(`[FAILED QUERY] ${name}: ${(performance.now() - start).toFixed(0)}ms`, error)
    throw error
  }
}
 
// Usage
const posts = await timedQuery('getAllPosts', () =>
  db.select().from(postsTable).where(eq(postsTable.published, true))
)

> Here are the last 100 error logs from production (from CloudWatch):
> [paste logs]
> Group by error type, frequency, affected endpoints, and time pattern.
> Prioritize which to fix first based on user impact.

// components/ErrorBoundary.tsx
'use client'
import * as Sentry from '@sentry/nextjs'
import { Component, type ReactNode } from 'react'
 
interface Props { children: ReactNode; fallback: ReactNode }
 
export class ErrorBoundary extends Component<Props, { hasError: boolean }> {
  state = { hasError: false }
  static getDerivedStateFromError() { return { hasError: true } }
 
  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    Sentry.captureException(error, {
      contexts: { react: { componentStack: errorInfo.componentStack } },
    })
  }
 
  render() {
    return this.state.hasError ? this.props.fallback : this.props.children
  }
}

> Blog post page crashes on mobile Safari: "ReferenceError: structuredClone is not defined"
> Device: iPhone 12, iOS 16.2. Help me reproduce this locally.

// structuredClone unavailable in WKWebView (in-app browsers)
// Fix: add a polyfill
if (typeof structuredClone === 'undefined') {
  globalThis.structuredClone = <T>(obj: T): T => JSON.parse(JSON.stringify(obj))
}

// lib/feature-flags.ts
type FeatureFlag = 'new-checkout' | 'v2-search'
 
const FLAGS: Record<FeatureFlag, { enabled: boolean; rollout: number }> = {
  'new-checkout': { enabled: true, rollout: 0.1 },  // 10%
  'v2-search': { enabled: false, rollout: 0 },
}
 
export function isFeatureEnabled(flag: FeatureFlag, userId: string): boolean {
  const config = FLAGS[flag]
  if (!config.enabled) return false
  const hash = [...(userId + flag)].reduce(
    (h, c) => ((h << 5) - h + c.charCodeAt(0)) | 0, 0
  )
  return (Math.abs(hash) % 100) / 100 < config.rollout
}

# Debugging Conventions
 
## Error Handling Rules
- All async functions must have try/catch with specific error types
- Never catch and swallow errors silently — always log or rethrow
- API routes must return structured error responses
- Client components must have error boundaries
 
## Logging Standards
- Structured logging (JSON in production)
- Levels: error, warn, info, debug
- Always include: timestamp, request ID, user ID (anonymized)
- Never log: passwords, tokens, PII
 
## When Debugging
1. Read the full error + stack trace before making changes
2. Form a hypothesis, add targeted logging
3. Verify fix doesn't break tests, add regression test
4. Remove debug logging before committing
 
## Debug Commands
- `npm run build 2>&1 | head -50` — check build errors
- `npx tsc --noEmit` — type check without building
- `DEBUG=* npm run dev` — verbose debug output
 
## Common Issues
- Hydration mismatch: browser-only APIs in SSR → wrap in useEffect
- "Module not found": check import path case sensitivity
- Stale data: check revalidation settings in fetch()

> Find where the "last updated" date is formatted in the blog post page.

// lib/utils.ts — the problematic function
export function formatDate(dateString: string, locale: Locale): string {
  const date = new Date(dateString)
  return date.toLocaleDateString(locale === 'zh' ? 'zh-CN' : 'en-US', {
    year: 'numeric', month: 'long', day: 'numeric',
    hour: 'numeric', minute: '2-digit', // includes time — timezone-sensitive!
  })
}

// Option 1: Use UTC explicitly (recommended for blogs)
export function formatDate(dateString: string, locale: Locale): string {
  return new Date(dateString).toLocaleDateString(
    locale === 'zh' ? 'zh-CN' : 'en-US',
    { year: 'numeric', month: 'long', day: 'numeric', timeZone: 'UTC' }
  )
}
 
// Option 2: Client-only rendering with useEffect (for user-local times)
// Option 3: suppressHydrationWarning (escape hatch — use sparingly)

// lib/utils.ts — fixed
export function formatDate(dateString: string, locale: Locale): string {
  return new Date(dateString).toLocaleDateString(
    locale === 'zh' ? 'zh-CN' : 'en-US',
    { year: 'numeric', month: 'long', day: 'numeric', timeZone: 'UTC' }
  )
}

> Write a test for formatDate that verifies it produces the same output
> regardless of the system timezone. This should prevent the hydration
> mismatch from coming back.

// lib/__tests__/utils.test.ts
import { describe, it, expect } from 'vitest'
import { formatDate } from '../utils'
 
describe('formatDate', () => {
  it('formats dates consistently regardless of timezone', () => {
    expect(formatDate('2026-03-12T15:30:00Z', 'en')).toBe('March 12, 2026')
    expect(formatDate('2026-03-12T15:30:00Z', 'zh')).toBe('2026年3月12日')
  })
 
  it('handles midnight UTC without date shift', () => {
    expect(formatDate('2026-03-12T00:00:00Z', 'en')).toBe('March 12, 2026')
  })
})

# Run the test
npx vitest run lib/__tests__/utils.test.ts

> I have a hydration mismatch. Help me debug it:
> 1. What exact text/HTML differs between server and client?
> 2. Which component renders this content?
> 3. Does it use Date/time, random values, window/document, or localStorage?
> 4. Was this component recently changed?