Guides
Troubleshooting by stage
Troubleshooting by stage.
| Symptom | Check first | Next action |
|---|---|---|
| 401 / 403 | API Key, matching Project ID, service host, feature entitlement | Correct configuration; repeated retries do not grant access |
| Create timeout | Reserved session ID and console session state | Inspect before retrying; close abandoned sessions |
| CDP cannot connect | Session active, returned URL reachable, proxy/firewall WebSocket support | Use the returned URL unchanged; do not log its credentials |
| Unsupported CDP method | Engine and exact method | Reproduce on Chromium and report the method |
| Navigation timeout | Target accessibility, proxy route, page readiness condition | Test one URL and a specific selector |
| Context locked | Owning session and asynchronous close | Wait for release; do not force-unlock a live writer |
| Proxy 407 | Provider credentials | Verify upstream settings without printing secrets |
| Web Fetch error | HTTP status, structured error, request_id | Follow Web Fetch errors |
A useful report
Include time and timezone, CN/global service, SDK/CLI version, browser mode, operation, sanitized error, session ID or request_id, and a minimal reproduction. Include expected versus actual behavior. Remove API keys, authenticated connect URLs, proxy passwords, cookies, and personal page content.
A healthy View page does not prove your local network can open the automation WebSocket. A ready session does not prove a target page allows access. A successful close request does not prove a Context lock has already been released.
Start from the minimal Playwright example, add one feature at a time, and keep the cleanup sequence when reducing the reproduction.