gh-ulasbilgen-mcp-skills-plugins-chrome-devtools-plugin/skills/mcp-chrome-devtools/reference/troubleshooting.md

Troubleshooting Guide

Common issues and solutions for chrome-devtools skill.

Table of Contents

• Connection Issues
• Page Management Problems
• Element Interaction Issues
• Snapshot and Screenshot Problems
• Console and Network Debugging
• Performance Analysis Issues
• General Best Practices

---

Connection Issues

Problem: "Cannot connect to mcp2rest"

Symptoms:

• Scripts fail with connection error
• "ECONNREFUSED" error on port 28888

Solutions:

1. Check if mcp2rest is running:

curl http://localhost:28888/health

Expected: {"status": "healthy"}

2. Start mcp2rest if not running:

mcp2rest start

3. Verify chrome-devtools server is loaded:

curl http://localhost:28888/servers

Should list chrome-devtools with "connected" status.

4. Reload server if disconnected:

mcp2rest reload chrome-devtools

Problem: "Server not found"

Symptoms:

• Server not listed in mcp2rest
• Tools return "server not configured" error

Solutions:

1. Check installed servers:

mcp2rest list

2. Add chrome-devtools server:

mcp2rest add chrome-devtools

3. Restart mcp2rest:

mcp2rest restart

---

Page Management Problems

Problem: "Cannot close last page"

Symptoms:

• close_page fails with error about last page

Solution:

Always keep at least one page open. Open a new page before closing the last one:

# Check current pages
node scripts/list_pages.js

# Open new page first
node scripts/new_page.js --url https://example.com

# Now close the old page
node scripts/close_page.js --pageIdx 1

Problem: "Page index out of range"

Symptoms:

• select_page or close_page fails
• "Invalid page index" error

Solutions:

1. Always list pages first:

node scripts/list_pages.js

2. Use indices from the current list: Page indices shift when pages are closed. Always get fresh indices.

3. Close pages in reverse order:

# If closing multiple pages, start from highest index
node scripts/close_page.js --pageIdx 3
node scripts/close_page.js --pageIdx 2
node scripts/close_page.js --pageIdx 1

Problem: "Navigation timeout"

Symptoms:

• new_page or navigate_page times out
• Page doesn't load within timeout period

Solutions:

1. Increase timeout:

node scripts/new_page.js --url https://slow-site.com --timeout 60000

2. Check network connectivity: Verify the URL loads in a regular browser.

3. Use emulation to debug slow loading:

# Test without throttling first
node scripts/emulate.js --cpuThrottlingRate 1
node scripts/new_page.js --url https://example.com

Problem: "Wrong page context"

Symptoms:

• Commands execute on wrong page
• Unexpected elements in snapshot

Solutions:

1. Check selected page:

node scripts/list_pages.js
# Look for "(selected)" indicator

2. Explicitly select target page:

node scripts/select_page.js --pageIdx 0

3. Pattern: Always select before interaction:

node scripts/list_pages.js
node scripts/select_page.js --pageIdx 1
node scripts/take_snapshot.js

---

Element Interaction Issues

Problem: "Element UID not found"

Symptoms:

• click, fill, or hover fails
• "UID does not exist" error

Solutions:

1. Take fresh snapshot: UIDs regenerate on each snapshot. Never reuse old UIDs.

# Always take new snapshot before interaction
node scripts/take_snapshot.js
# Use UIDs from this output
node scripts/click.js --uid <fresh-uid>

2. Verify element exists: Check the snapshot output to confirm the element is present.

3. Wait for page to load:

node scripts/wait_for.js --text "Page loaded" --timeout 10000
node scripts/take_snapshot.js

Problem: "Click doesn't trigger action"

Symptoms:

• Element is clicked but nothing happens
• No error, but expected behavior doesn't occur

Solutions:

1. Wait for page to fully load:

node scripts/wait_for.js --text "Ready" --timeout 5000
node scripts/click.js --uid button_abc

2. Try hover first: Some elements require hover to become clickable.

node scripts/hover.js --uid element_abc
node scripts/click.js --uid element_abc

3. Check if element is visible: Hidden or off-screen elements may not be clickable. Use take_snapshot with verbose to check visibility.

4. Use double-click if needed:

node scripts/click.js --uid element_abc --dblClick true

Problem: "Fill doesn't work on input"

Symptoms:

• Text not entered into field
• Select dropdown not changing

Solutions:

1. Verify element type: Use take_snapshot to confirm it's an input/textarea/select.

2. Click to focus first:

node scripts/click.js --uid input_abc
node scripts/fill.js --uid input_abc --value "text"

3. For custom components, use press_key:

node scripts/click.js --uid custom_input
node scripts/press_key.js --key "H"
node scripts/press_key.js --key "i"

4. For dropdowns, use exact option value: Check the HTML to find the correct option value.

Problem: "Drag and drop doesn't work"

Symptoms:

• Drag operation completes but element doesn't move
• "Invalid UID" error

Solutions:

1. Verify both UIDs are current:

node scripts/take_snapshot.js
# Use UIDs from this output
node scripts/drag.js --from-uid <fresh-from> --to-uid <fresh-to>

2. Add wait between operations:

node scripts/drag.js --from-uid item1 --to-uid zone1
node scripts/wait_for.js --text "Moved" --timeout 3000

3. Check if dropzone accepts the element: Some drag-and-drop UIs have restrictions on what can be dropped where.

Problem: "File upload fails"

Symptoms:

• upload_file fails
• File path error

Solutions:

1. Use absolute paths:

# Good
node scripts/upload_file.js --uid input_file --filePath /Users/username/file.pdf

# Bad
# node scripts/upload_file.js --uid input_file --filePath ./file.pdf

2. Use forward slashes:

# Good
/Users/username/documents/file.pdf

# Bad (Windows-style)
# C:\Users\username\documents\file.pdf

3. Verify file exists:

ls -la /Users/username/documents/file.pdf

4. Check file input UID: Take fresh snapshot and verify the element is a file input.

---

Snapshot and Screenshot Problems

Problem: "Snapshot shows different UIDs each time"

Symptoms:

• UIDs change on each snapshot
• Previously working UIDs stop working

Solution:

This is expected behavior. UIDs are dynamically generated on each snapshot. Always use the most recent snapshot:

# Pattern: Always snapshot before interaction
node scripts/take_snapshot.js
# Immediately use UIDs from output
node scripts/click.js --uid <current-uid>

Problem: "Screenshot is blank or black"

Symptoms:

• Screenshot file is created but shows blank/black image

Solutions:

1. Wait for page to render:

node scripts/wait_for.js --text "Content" --timeout 10000
node scripts/take_screenshot.js --filePath page.png

2. Try full page screenshot:

node scripts/take_screenshot.js --fullPage true --filePath page.png

3. Verify element is visible: For element screenshots, ensure the element isn't hidden or off-screen.

4. Check page actually loaded:

node scripts/take_snapshot.js
# Verify page content appears in snapshot

Problem: "Screenshot file not saving"

Symptoms:

• No error but file not created
• "File not found" when opening

Solutions:

1. Use absolute path:

node scripts/take_screenshot.js --filePath /Users/username/screenshots/page.png

2. Ensure directory exists:

mkdir -p /Users/username/screenshots
node scripts/take_screenshot.js --filePath /Users/username/screenshots/page.png

3. Check file permissions: Ensure you have write access to the target directory.

---

Console and Network Debugging

Problem: "Console messages not showing up"

Symptoms:

• list_console_messages returns empty or incomplete results

Solutions:

1. Messages accumulate since navigation: Console messages are captured from the current page navigation onwards.

2. Reload if needed:

node scripts/navigate_page.js --type reload
# Wait for page load
node scripts/wait_for.js --text "Ready" --timeout 10000
# Now check console
node scripts/list_console_messages.js

3. Include preserved messages:

node scripts/list_console_messages.js --includePreservedMessages true

4. Ensure page has errors to show: Use take_snapshot or evaluate_script to verify page loaded correctly.

Problem: "Network requests list is empty"

Symptoms:

• list_network_requests returns no results
• Expected API calls not showing

Solutions:

1. Requests are captured from navigation onwards:

# Navigate first to capture requests
node scripts/navigate_page.js --url https://example.com
# Wait for page to load
node scripts/wait_for.js --text "Loaded" --timeout 10000
# Now check requests
node scripts/list_network_requests.js

2. Filter by resource type:

# Maybe filtering too strictly
node scripts/list_network_requests.js --resourceTypes fetch,xhr,document

3. Include preserved requests:

node scripts/list_network_requests.js --includePreservedRequests true

Problem: "Cannot find console message or network request ID"

Symptoms:

• get_console_message or get_network_request fails
• "Invalid ID" error

Solutions:

1. List first to get IDs:

# For console
node scripts/list_console_messages.js
# Copy message ID from output
node scripts/get_console_message.js --msgid <id-from-list>

# For network
node scripts/list_network_requests.js
# Copy request ID from output
node scripts/get_network_request.js --reqid <id-from-list>

2. IDs are session-specific: IDs don't persist across page navigations. Get fresh IDs after navigation.

---

Performance Analysis Issues

Problem: "evaluate_script returns null or error"

Symptoms:

• Script execution fails
• Returns null unexpectedly
• "Evaluation failed" error

Solutions:

1. Return JSON-serializable values only:

# Good: primitives, arrays, plain objects
node scripts/evaluate_script.js --function "() => document.title"
node scripts/evaluate_script.js --function "() => [1, 2, 3]"
node scripts/evaluate_script.js --function "() => ({key: 'value'})"

# Bad: DOM nodes, functions, circular references
# node scripts/evaluate_script.js --function "() => document.querySelector('div')"

2. Extract values from DOM elements:

# Instead of returning DOM nodes, extract their properties
node scripts/evaluate_script.js --function "() => Array.from(document.querySelectorAll('a')).map(a => a.href)"

3. Check for JavaScript errors:

node scripts/list_console_messages.js --types error

4. Verify function syntax:

# Arrow function
node scripts/evaluate_script.js --function "() => document.title"

# Function with parameters
node scripts/evaluate_script.js --function "(x, y) => x + y" --args '[5, 3]'

Problem: "wait_for times out"

Symptoms:

• wait_for exceeds timeout
• Text never appears

Solutions:

1. Increase timeout:

node scripts/wait_for.js --text "Loaded" --timeout 30000

2. Verify text actually appears:

# Check with snapshot
node scripts/take_snapshot.js
# Look for the expected text

3. Text match is exact: Check spelling, capitalization, and spacing.

# Case-sensitive match
# "Welcome" ≠ "welcome" ≠ "Welcome!"

4. Wait for network first:

# If text appears after API call, wait longer
node scripts/wait_for.js --text "Data loaded" --timeout 20000

Problem: "Dialog not handled"

Symptoms:

• handle_dialog fails
• "No dialog present" error

Solutions:

1. Dialog must be open first:

# Trigger dialog
node scripts/click.js --uid button_delete

# Immediately handle it
node scripts/handle_dialog.js --action accept

2. Some "dialogs" are custom HTML: If it's not a real browser dialog (alert/confirm/prompt), use click instead:

# For custom modal dialogs
node scripts/take_snapshot.js
node scripts/click.js --uid button_modal_ok

3. Timing matters: Handle dialog immediately after triggering action.

Problem: "Performance trace shows unexpected results"

Symptoms:

• CWV scores don't match expectations
• Missing performance data

Solutions:

1. Ensure page fully loads:

node scripts/performance_start_trace.js --reload true --autoStop false
node scripts/wait_for.js --text "Loaded" --timeout 20000
node scripts/performance_stop_trace.js

2. Use reload for consistent measurement:

# For initial page load measurement
node scripts/performance_start_trace.js --reload true --autoStop false

3. Clear browser state: Navigation with cache clear:

node scripts/navigate_page.js --url https://example.com --ignoreCache true

4. Disable emulation if active:

node scripts/emulate.js --cpuThrottlingRate 1

Problem: "Emulation not working"

Symptoms:

• Page loads at normal speed despite emulation
• No visible effect from throttling

Solutions:

1. Emulation persists for session: Reset to normal first, then apply:

# Reset
node scripts/emulate.js --cpuThrottlingRate 1

# Then apply desired emulation
node scripts/emulate.js --cpuThrottlingRate 4

2. Network conditions must be valid JSON:

# All three properties required
node scripts/emulate.js --networkConditions '{"downloadThroughput":50000,"uploadThroughput":50000,"latency":2000}'

3. Verify effect with performance trace:

node scripts/emulate.js --cpuThrottlingRate 4
node scripts/performance_start_trace.js --reload true --autoStop false
node scripts/wait_for.js --text "Loaded" --timeout 60000
node scripts/performance_stop_trace.js
# Check timing metrics in output

---

General Best Practices

Always Snapshot Before Interaction

UIDs are dynamic. Take a fresh snapshot before every interaction:

# Good pattern
node scripts/take_snapshot.js
node scripts/click.js --uid <current-uid>

# Bad pattern (will fail)
# node scripts/take_snapshot.js
# ... do other things ...
# node scripts/click.js --uid <old-uid>  # UID expired!

Wait After Actions

Allow time for UI updates:

node scripts/click.js --uid button_submit
node scripts/wait_for.js --text "Success" --timeout 5000
node scripts/take_snapshot.js

Use Absolute Paths

Always use absolute paths for files:

# Good
/Users/username/documents/file.pdf
/home/user/screenshots/page.png

# Bad
./file.pdf
../screenshots/page.png

Check Connection First

Before running workflows, verify mcp2rest is healthy:

curl http://localhost:28888/health

List Before Selecting

Always list pages before selecting or closing:

node scripts/list_pages.js
node scripts/select_page.js --pageIdx 1

Handle Errors Gracefully

Check console and network for debugging:

# After error occurs
node scripts/list_console_messages.js --types error
node scripts/list_network_requests.js
node scripts/take_screenshot.js --filePath error_state.png

Use Verbose for Debugging

Get more details when troubleshooting:

node scripts/take_snapshot.js --verbose true

Save Outputs for Analysis

Redirect output to files for later review:

node scripts/list_console_messages.js > console_log.txt
node scripts/list_network_requests.js > network_log.txt
node scripts/take_snapshot.js --filePath snapshot.txt

---

Getting Help

If you encounter issues not covered here:

1. Check tool documentation: @reference/all-tools.md
2. Review workflows: @workflows/[tool-group].md
3. Test with minimal example: Isolate the problem with simplest reproduction
4. Check mcp2rest status: Ensure server is connected and healthy
5. Restart mcp2rest: Sometimes a fresh start helps: mcp2rest restart