Troubleshooting
Start with the service state and logs:
docker compose psdocker compose logs server workercurl -fsS http://localhost:8080/readyzThe client cannot connect
Section titled “The client cannot connect”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.
HTTP errors
Section titled “HTTP errors”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.
Requests return 401
Section titled “Requests return 401”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.
Requests wait or return 429
Section titled “Requests wait or return 429”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.
Several sessions end together
Section titled “Several sessions end together”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.
Chromium fails during startup
Section titled “Chromium fails during startup”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.