Debug Console

Debug with Console

Captures and analyzes console errors from web applications using Chrome DevTools MCP.

Token Efficiency: Eliminates manual console inspection pattern (60% savings: 2,000 → 800 tokens)

Usage

Invoke with: /debug-console [url]

Examples:

• /debug-console - Debug current page (if browser already open)
• /debug-console http://localhost:3000/app/scheduler - Navigate and debug specific page
• /debug-console http://localhost:3000 - Debug homepage

Prerequisites

• Chrome DevTools MCP enabled: claude --chrome
• Chrome browser running with Claude in Chrome extension
• Application running on localhost:3000

Workflow

Step 1: Navigate to URL

If URL provided:

mcp__playwright__browser_navigate({ url: "[provided-url]" })

If no URL provided:

• Use current page in Chrome browser
• Skip navigation step

Step 2: Capture Console Messages

Capture errors and warnings:

mcp__playwright__browser_console_messages({ level: "error" })

Filter criteria:

• Level: "error" includes errors and warnings (higher severity levels included)
• JavaScript errors
• Network failures (404, 500, CORS errors)
• React/Next.js errors
• Runtime exceptions

Step 3: Analyze Errors

Group errors by type:

1. Syntax Errors: Parse errors, invalid syntax
2. Runtime Errors: TypeError, ReferenceError, null/undefined access
3. Network Errors: Failed fetches, 404s, CORS issues
4. Framework Errors: React hydration, Next.js errors
5. Third-party Errors: External library errors

Extract details:

• Error message (full text)
• File location (file:line:column)
• Stack trace (if available)
• Error count (number of occurrences)
• Timestamp (when error occurred)

Step 4: Report Findings

Create structured summary:

## Console Debug Report: [URL]

**Date**: [timestamp]
**Browser**: Chrome (via Chrome DevTools MCP)

### Summary
- Total errors: [count]
- Critical errors: [count] (blocking functionality)
- Warnings: [count] (non-blocking issues)
- Network failures: [count]

### Critical Errors

#### 1. [Error Type] - [Severity]
- **Message**: [error message]
- **Location**: [file:line:column]
- **Type**: [TypeError | ReferenceError | NetworkError | etc.]
- **Stack Trace**:

[stack trace if available]

- **Occurrences**: [count]
- **Impact**: [description of what's broken]
- **Recommendation**: [specific fix suggestion]

[Repeat for each critical error]

### Warnings

#### 1. [Warning Type]
- **Message**: [warning message]
- **Location**: [file:line:column]
- **Recommendation**: [fix suggestion]

[Repeat for each warning]

### Network Failures

#### 1. [Request URL]
- **Status**: [404 | 500 | etc.]
- **Type**: [CORS | Timeout | Server Error]
- **Recommendation**: [fix suggestion]

[Repeat for each network failure]

### Next Steps

**Immediate actions**:
1. [Fix critical error 1]
2. [Fix critical error 2]
3. [Address network failures]

**Optional improvements**:
1. [Address warnings]
2. [Performance optimizations based on console logs]

Step 5: Save Report (if critical errors found)

Only save if:

• Critical errors count > 0
• OR warnings count > 3
• OR network failures count > 1

Save location: .claude/logs/debug_console_[timestamp].md

If no critical issues:

• Report summary directly to user
• Don't create log file (token efficiency)

Success Criteria

• All console errors captured (error level and above)
• Errors categorized by type (syntax, runtime, network, framework)
• File locations extracted (file:line:column)
• Stack traces included for critical errors
• Actionable recommendations provided for each error
• Report format clear and structured

Error Handling

Common Issues

Issue: "Chrome DevTools MCP not available"

• Solution: Start Claude Code with claude --chrome
• Fallback: Suggest manual console inspection

Issue: "Browser not responding"

• Solution: Check for modal dialogs blocking browser
• Action: Dismiss dialogs manually or create new tab

Issue: "No console messages found"

• Result: Report "No errors found" (success case)
• Action: Inform user app is running without console errors

Issue: "Too many console messages (>100)"

• Solution: Use head_limit to capture first 50 errors
• Action: Note in report: "First 50 errors shown (total: [count])"

Examples

Example 1: Simple Debug

User: /debug-console http://localhost:3000/app/scheduler

Output:

## Console Debug Report: http://localhost:3000/app/scheduler

### Summary
- Total errors: 2
- Critical errors: 1
- Warnings: 1

### Critical Errors

#### 1. TypeError - Critical
- **Message**: Cannot read properties of undefined (reading 'shifts')
- **Location**: SchedulerView.tsx:42:15
- **Type**: TypeError (Runtime Error)
- **Stack Trace**:

at SchedulerView (SchedulerView.tsx:42:15) at renderWithHooks (react-dom.production.min.js:14985)

- **Occurrences**: 1
- **Impact**: Scheduler fails to render shift data
- **Recommendation**: Add null check before accessing shifts: `data?.shifts?.map(...)`

### Warnings

#### 1. React Hydration Warning
- **Message**: Text content did not match. Server: "0 shifts" Client: "Loading..."
- **Location**: ShiftCount.tsx:15:8
- **Recommendation**: Ensure server and client render same initial state

### Next Steps

**Immediate actions**:
1. Fix TypeError in SchedulerView.tsx line 42 (add null check)
2. Review React hydration in ShiftCount component

Example 2: No Errors Found

User: /debug-console

Output:

## Console Debug Report: http://localhost:3000/app/scheduler

✅ No errors found!

**Summary**:
- Total errors: 0
- Warnings: 0
- Network failures: 0

The application is running without console errors.

Example 3: Network Failures

User: /debug-console http://localhost:3000/app/dashboard

Output:

## Console Debug Report: http://localhost:3000/app/dashboard

### Summary
- Total errors: 0
- Network failures: 2

### Network Failures

#### 1. GET /api/trpc/users.getAll
- **Status**: 500 Internal Server Error
- **Type**: Server Error
- **Recommendation**: Check server logs for tRPC procedure error

#### 2. GET /api/trpc/metrics.getWeekly
- **Status**: 404 Not Found
- **Type**: Missing Endpoint
- **Recommendation**: Verify tRPC router includes metrics.getWeekly procedure

### Next Steps

**Immediate actions**:
1. Check backend server logs for users.getAll error
2. Add metrics.getWeekly procedure to tRPC router

Integration with Development Workflow

When to use this Skill:

• ✅ After implementing new feature (verify no console errors)
• ✅ Before committing code (pre-commit check)
• ✅ When user reports "app not working" (debug console first)
• ✅ After deployment to localhost (sanity check)
• ✅ When debugging UI issues (check for JavaScript errors)

When NOT to use:

• ❌ For formal E2E tests (use Playwright test framework instead)
• ❌ For production debugging (use production monitoring tools)
• ❌ For performance profiling (use Chrome DevTools profiler directly)

Related Tools and Skills

• auth-verify Skill: Authenticate before debugging authenticated pages
• PLAYWRIGHT_MCP_AUTOMATION.md: Browser automation patterns
• Chrome DevTools MCP: Native browser debugging capabilities

Token Efficiency

Baseline (manual console inspection):

• Read PLAYWRIGHT_MCP_AUTOMATION.md: 1,200 tokens
• Navigate to page: 200 tokens
• Capture console: 300 tokens
• Analyze and format report: 300 tokens
• Total: ~2,000 tokens

With debug-console Skill:

• Skill invocation: 200 tokens
• Console capture + analysis: 400 tokens
• Report generation: 200 tokens
• Total: ~800 tokens

Savings: 1,200 tokens (60% reduction)

Projected usage: 10x per week Weekly savings: 12,000 tokens Annual savings: 624,000 tokens (~$1.50/year)

Skill Version: 1.0 Created: 2026-01-09 Last Updated: 2026-01-09 Requires: Claude Code v2.1.0+, Chrome DevTools MCP