Skip to content

Troubleshooting

Start with the service state and logs:

Terminal window
docker compose ps
docker compose logs server worker
curl -fsS http://localhost:8080/readyz
Server ready?
-> API key accepted?
-> Worker registered?
-> Pool, browser, and Playwright versions match?
-> Server can reach worker?

Check the endpoint and browser type. chromium.connect() needs a Chromium worker. Firefox and WebKit need their own workers and ?browser= selection.

Check the client’s Playwright version against the worker. The major and minor versions must match. BrowserThing v0.10.0 images use Playwright 1.65.0.

REST requests and failed WebSocket connections can return these statuses:

Status Cause Next action
400 A WebSocket connection has an unknown browser or an invalid pool name. Read the error message. Check the connection URL.
401 The API key is missing, invalid, or revoked. Give clients and workers a valid key.
409 A session already has a client, or the attaching client’s Playwright version does not match. Read the error message. Use a new session or a matching client version.
410 The session is completed, failed, or expired. Create a new session. A closed session cannot be resumed.
422 A REST request has invalid fields, or requests mode: dedicated, which is not supported. Check the response details. Omit mode or use default; check the browser type and version.
429 All matching capacity is busy and the queue is full or disabled. Close unused sessions, reduce concurrency, or add workers.
503 A queued request timed out, the server is shutting down, or the authentication service is unavailable. Read the error body. Check worker availability, browser/version matches, database access, and server logs. Admission errors include Retry-After: 1.

The 409 and 410 statuses apply when attaching to /sessions/{id}. Read a REST error body with curl -sS -i; curl -f hides the response body.

The server requires a key for every request except /healthz and /readyz. With zero active keys, it refuses every request and logs how to create a key. Give workers WORKER_API_KEY, and give clients an authorization header or a token query parameter. Recreate workers after you change their environment variables.

A remote worker registers but connections fail

Section titled “A remote worker registers but connections fail”

The worker can reach the server, but the server may not be able to reach the worker. Set PRIVATE_HOSTNAME to an address the server can resolve and reach. Publish the configured PORT and permit traffic from the server through the worker host’s firewall.

Inspect GET /v1/capacity with an API key. Check available slots, queue depth, and worker health. Close client connections after use. Add workers if the workload needs more capacity, and measure CPU and memory before you increase MAX_SLOTS.

For a 503 queue timeout, also check that a worker matches the requested pool, browser, and Playwright version. Free slots in a different pool, or on a different browser or version, cannot serve the request. If no registered worker matches, the message names the request and lists the registered workers with their pools, for example session queue wait timed out: no worker serves chromium with Playwright 1.65 in pool long; registered workers: chromium 1.65.0 in pool default. Check the spelling of ?pool= against the worker’s POOL. Admission waits up to QUEUE_WAIT_TIMEOUT (30 seconds by default). After Retry-After, use a limited retry count with increasing delays.

Sessions on one worker share a browser process. A browser crash ends those sessions. Recycling also closes remaining sessions when DRAIN_TIMEOUT expires. A server restart ends connections on that relay. Sessions that start together also end together when they reach MAX_SESSION_DURATION. Check logs before you retry work, especially if the automation changes data on other sites. A new connection starts a new session; it does not resume the earlier task.

Calls fail with “session exceeded MAX_SESSION_DURATION”

Section titled “Calls fail with “session exceeded MAX_SESSION_DURATION””

Playwright calls fail with session exceeded MAX_SESSION_DURATION (<value>) after the server closes the connection with WebSocket code 1008. The session was connected for longer than the server’s MAX_SESSION_DURATION. Close the browser connection when a task is done, and split long work into shorter sessions. If the work needs more time, increase the value on all server replicas, or set 0 to disable the limit. See the configuration reference.

Use the supplied Compose file with init: true, the seccomp profile, and shared memory settings. Keep the worker’s non-root user. Check the worker logs for the startup failure instead of disabling the sandbox.

If you file a GitHub issue, include the BrowserThing and Playwright versions, browser type, and relevant logs. Remove API keys and private URLs before you share them.