> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: Troubleshooting
description: Debug connection issues, read relay logs, and fix common problems.
icon: lucide:bug
---

## Relay server logs

The relay server logs everything: extension connections, CDP events, MCP messages, and errors. Two log files are created each time the server starts:

```bash
playwriter logfile
# prints paths like:
#   ~/.playwriter/relay-server.log
#   ~/.playwriter/cdp.jsonl
```

**`relay-server.log`** contains human-readable logs from the extension, MCP, and WebSocket server.

**`cdp.jsonl`** is a JSON Lines file with every CDP command, response, and event. Long strings are truncated. Use `jq` to analyze traffic:

```bash
# Count CDP messages by direction and method
jq -r '.direction + "\t" + (.message.method // "response")' ~/.playwriter/cdp.jsonl | uniq -c

# Find errors
grep -i error ~/.playwriter/relay-server.log | tail -20
```

Both files are **recreated** every time the server starts, so they only contain logs from the current session.

## Known issues

### All pages return `about:blank`

This is a Chrome bug in the `chrome.debugger` API. **Fix:** restart Chrome completely (quit and reopen), then click the extension icon again.

### Browser switches to light mode on connect

Playwright triggers a theme change when connecting via CDP. This is an [upstream Playwright issue](https://github.com/microsoft/playwright/issues/37627). The browser returns to its normal theme when the session disconnects.

## Common problems

### "Extension is not connected"

The extension isn't connected to the relay. Check:

1. Is Chrome running?
2. Did you click the extension icon on at least one tab? (Icon should be green)
3. Is the relay server running? The CLI starts it automatically, but if you killed it manually, run `playwriter serve` or just use any CLI command to restart it

### "No browser tabs have Playwriter enabled"

You need to click the extension icon on a tab to make it controllable. The extension only attaches to tabs where you explicitly enable it.

### Connection is stale or broken

Reset the session to reconnect:

```bash
playwriter session reset <sessionId>
```

If that doesn't help, restart the relay by killing the process on port 19988 and running any CLI command:

```bash
# macOS/Linux
PIDS=$(lsof -ti :19988)
[ -n "$PIDS" ] && kill $PIDS

# Windows (PowerShell)
Get-NetTCPConnection -LocalPort 19988 -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }
```

### Timeout errors

Increase the timeout for slow operations:

```bash
playwriter -s 1 --timeout 30000 -e 'await page.goto("https://slow-site.com")'
```

The default timeout is 10 seconds.

### Port 19988 already in use

Another instance of the relay is running. Kill it first:

```bash
# macOS/Linux
PIDS=$(lsof -ti :19988)
[ -n "$PIDS" ] && kill $PIDS

# Or use --replace flag
playwriter serve --token MY_SECRET --replace
```