name: debugging-patterns description: Debugging strategies and error resolution patterns. Stack trace analysis, runtime errors, build errors, network issues. Use when debugging any type of error. allowed-tools: Read, Write, Edit, Bash, Grep, Glob

Debugging Patterns - Error Resolution Best Practices

Purpose

Expert guidance for debugging:

• Error Analysis - Stack traces, error messages
• Runtime Issues - Type errors, null references
• Build Errors - Compilation, bundling
• Network Issues - API, CORS, HTTP errors
• Performance Bugs - Slow operations, memory leaks

Debug Process

1. UNDERSTAND - What should happen vs what happens
   ↓
2. REPRODUCE - Consistent steps to trigger bug
   ↓
3. ISOLATE - Narrow down to specific code
   ↓
4. IDENTIFY - Find root cause
   ↓
5. FIX - Implement solution
   ↓
6. VERIFY - Confirm fix works + no regressions

Stack Trace Analysis

Reading Error Stack

TypeError: Cannot read properties of undefined (reading 'name')
    at getUserName (src/utils/user.ts:45:23)
    at ProfileCard (src/components/ProfileCard.tsx:12:18)
    at renderWithHooks (node_modules/react-dom/...)

Key Information:

• Error Type: TypeError
• Message: Cannot read properties of undefined
• Property: name
• Location: src/utils/user.ts:45:23 (file:line:column)
• Call Stack: Shows how we got here

Fix Pattern

// Error at line 45
function getUserName(user: User) {
	return user.name; // ERROR: user is undefined
}

// Fix: Add null check
function getUserName(user: User | undefined): string {
	return user?.name ?? 'Unknown';
}

// Or use assertion with clear error
function getUserName(user: User | undefined): string {
	if (!user) {
		throw new Error('User is required for getUserName');
	}
	return user.name;
}

Common Error Patterns

TypeError: Cannot read properties of undefined

// Pattern: Accessing property on undefined
const name = user.profile.name;

// Fix 1: Optional chaining
const name = user?.profile?.name ?? 'Unknown';

// Fix 2: Early return
if (!user?.profile) return null;
const name = user.profile.name;

// Fix 3: Default value
const profile = user?.profile ?? { name: 'Unknown' };

TypeError: X is not a function

// Pattern: Calling non-function
onClick(); // onClick is undefined

// Fix 1: Check before calling
onClick?.();

// Fix 2: Provide default
const handleClick = onClick ?? (() => {});
handleClick();

ReferenceError: X is not defined

// Pattern: Using undefined variable
console.log(userData); // userData not imported/declared

// Fix: Import or declare
import { userData } from './data';
// or
const userData = await fetchUserData();

SyntaxError: Unexpected token

// Pattern: Invalid JSON
const data = JSON.parse(response);
// SyntaxError: Unexpected token '<'

// Fix: Check response before parsing
if (!response.ok) {
	throw new Error(`HTTP ${response.status}`);
}
const text = await response.text();
try {
	return JSON.parse(text);
} catch {
	throw new Error(`Invalid JSON: ${text.slice(0, 100)}`);
}

TypeScript Errors

TS2339: Property does not exist

// Error
const env = process.env.NODE_ENV;
// Property 'NODE_ENV' does not exist on type 'ProcessEnv'

// Fix: Use bracket notation
const env = process.env['NODE_ENV'];

TS2532: Object is possibly undefined

// Error
const items = array.map((x) => x.value);
// Object is possibly 'undefined'

// Fix 1: Non-null assertion (if certain)
const items = array!.map((x) => x.value);

// Fix 2: Default value
const items = (array ?? []).map((x) => x.value);

// Fix 3: Conditional
const items = array ? array.map((x) => x.value) : [];

TS2345: Argument type mismatch

// Error
function greet(name: string) {}
greet(user.name); // Argument of type 'string | undefined'

// Fix 1: Provide default
greet(user.name ?? 'Guest');

// Fix 2: Assert
greet(user.name!);

// Fix 3: Guard
if (user.name) greet(user.name);

TS7053: Index signature

// Error
const value = obj[key];
// Element implicitly has 'any' type

// Fix: Type the index
const value = (obj as Record<string, unknown>)[key];

// Or define proper type
interface MyObj {
	[key: string]: string | undefined;
}

Build Errors

Module Not Found

# Error
Cannot find module './utils' or its corresponding type declarations

# Check 1: File exists?
ls src/utils.ts

# Check 2: Extension needed?
import { helper } from './utils.js';  # ESM requires extension

# Check 3: Path alias configured?
# Check tsconfig.json paths

Duplicate Identifier

# Error
Duplicate identifier 'User'

# Fix: Check imports for conflicts
# May have both named and default import
import User from './User';
import { User } from './types';  # Conflict!

# Solution: Rename one
import { User as UserType } from './types';

ESM/CJS Compatibility

// Error: require is not defined in ES module
const fs = require('fs');

// Fix: Use ESM import
import fs from 'fs';
import { readFileSync } from 'fs';

// If must use require in ESM
import { createRequire } from 'module';
const require = createRequire(import.meta.url);

Network & API Errors

CORS Errors

Access to fetch at 'https://api.example.com' has been blocked by CORS policy

// Server-side fix (add headers)
res.setHeader('Access-Control-Allow-Origin', 'https://yoursite.com');
res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');

// Client-side workaround (proxy in dev)
// vite.config.ts
export default {
	server: {
		proxy: {
			'/api': {
				target: 'https://api.example.com',
				changeOrigin: true,
			},
		},
	},
};

HTTP Error Handling

async function fetchWithErrorHandling<T>(url: string): Promise<T> {
	const response = await fetch(url);

	if (!response.ok) {
		// Get error details
		let message: string;
		try {
			const error = await response.json();
			message = error.message || response.statusText;
		} catch {
			message = response.statusText;
		}

		throw new Error(`${response.status} ${message}`);
	}

	return response.json();
}

Network Timeout

async function fetchWithTimeout(url: string, timeout = 5000) {
	const controller = new AbortController();
	const id = setTimeout(() => controller.abort(), timeout);

	try {
		const response = await fetch(url, { signal: controller.signal });
		clearTimeout(id);
		return response;
	} catch (error) {
		clearTimeout(id);
		if (error instanceof Error && error.name === 'AbortError') {
			throw new Error(`Request timeout after ${timeout}ms`);
		}
		throw error;
	}
}

React Debugging

"Cannot update a component while rendering"

// Error: State update during render
function Component({ value }) {
	const [state, setState] = useState(0);
	setState(value); // ERROR!

	// Fix: Use useEffect
	useEffect(() => {
		setState(value);
	}, [value]);
}

"Too many re-renders"

// Error: Infinite loop
function Component() {
	const [count, setCount] = useState(0);
	setCount(count + 1); // Causes re-render, which sets count...

	// Fix: Add condition or use effect
	useEffect(() => {
		if (count < 10) {
			setCount((c) => c + 1);
		}
	}, [count]);
}

"Invalid hook call"

// Error: Hook outside component or conditional
function Component() {
	if (condition) {
		const [state] = useState(0); // ERROR!
	}
}

// Fix: Hooks must be at top level
function Component() {
	const [state] = useState(0); // OK
	if (condition) {
		// use state here
	}
}

Debug Commands

Git - Find Breaking Commit

# Start bisect
git bisect start
git bisect bad HEAD
git bisect good abc123  # Last known good commit

# Test and mark each commit
git bisect good  # or bad

# End bisect
git bisect reset

Find Error in Code

# Search for error message
grep -rn "specific error text" src/

# Search for pattern
grep -rn "throw new Error" src/ --include="*.ts"

# Find file with symbol
grep -rn "functionName" src/ --include="*.ts" -l

Bun Debugging

# Debug mode
bun --inspect src/index.ts

# With breakpoint on start
bun --inspect-brk src/index.ts

# Low memory mode (for memory issues)
bun --smol src/index.ts

Debugging Checklist

Before You Start

• Can you reproduce the bug?
• Do you have the exact error message?
• What changed recently? (git log, git diff)

Investigation

• Read the full error message and stack trace
• Check the line number mentioned in error
• Add console.log at key points
• Check network tab for API errors

After Fix

• Does the fix work for all cases?
• Did you add tests to prevent regression?
• Did you handle edge cases?

Agent Integration

This skill is used by:

• debugger agent
• error-stack-analyzer agent
• type-error-resolver agent
• runtime-error-fixer agent
• network-debugger agent
• build-error-fixer agent

FORBIDDEN

1. Swallowing errors silently - Always log or handle
2. Using any to hide errors - Fix the actual type issue
3. @ts-ignore without comment - Use @ts-expect-error with explanation
4. Empty catch blocks - At minimum, log the error
5. Fixing symptoms not causes - Find and fix root cause

Version

• v1.0.0 - Initial implementation based on 2024-2025 debugging patterns