Troubleshooting

File Locations

• Config: ~/.pagerunner/config.toml
• Database: ~/.pagerunner/state.db
• Audit log: ~/.pagerunner/audit.log
• Recordings: ~/.pagerunner/recordings/
• NER models: ~/.pagerunner/models/ (only with --features ner)
• Daemon socket: ~/.pagerunner/daemon.sock

Debug Mode

Common Issues

"Chrome not found"

• Pagerunner needs Google Chrome installed (not Chromium)
• macOS: /Applications/Google Chrome.app
• Verify: ls "/Applications/Google Chrome.app"

"Session not found" / session_not_found

• Session was closed or Chrome crashed
• Run list_sessions to see active sessions
• Open a new session with open_session

"Chrome unreachable" / chrome_unreachable

• Chrome process may have crashed
• Check: pagerunner status (if using daemon)
• Fix: close the session and open a new one

"Selector not found" / selector_not_found

• CSS selector doesn't match any element on the page
• Use screenshot to see the current page state
• Use get_content to inspect available elements
• The page may not have finished loading — use wait_for first

"Permission denied" / permission_denied

• A security policy is blocking the action
• Check allowed_domains in your profile config
• Check allowed_tools / blocked_tools settings

"Navigation timeout" / navigation_timeout

• Page is slow to load
• Use wait_for with a longer timeout_ms
• Check if the URL is correct and the site is up

"Database locked"

• Another pagerunner process holds the DB lock
• If using daemon mode, MCP clients should auto-proxy through it
• Check: lsof ~/.pagerunner/state.db
• Fix: stop the other process, or use daemon mode

"Anonymization gap" / anonymization_gap

• PII was detected in content that should have been anonymized
• The content was blocked before reaching the LLM (safe)
• Consider adding custom patterns for domain-specific PII

Session Health States

• alive — normal operation
• reconnecting — brief CDP interruption, auto-reconnecting (retry in 2-3s)
• recovering — Chrome crashed, being restarted (retry in 5-10s)
• dead — Chrome gone, must close and reopen session

Checking Status