Tune Selenium Grid Session Queue Timeouts, Retries, and Batches

Selenium Grid session queue tuning controls how long new work waits, how quickly busy requests are reconsidered, and how much creation work the Distributor pulls at once. These settings cannot create browser capacity. They shape overload behavior, fairness, responsiveness after a slot becomes free, and the amount of pressure placed on Grid's scheduling components.

Tune them from measurements of real session creation and job cancellation, not from element timeout habits. A queued request has no browser yet. Increasing its allowance may help a legitimate burst, but it can also make an impossible capability wait longer and consume a CI worker that should have failed fast.

Follow a new-session request through the queue

The official Grid components guide describes the Router forwarding new-session requests to a FIFO queue. The Distributor polls for a first matching request, finds a suitable free Node slot, and returns busy requests to the queue when necessary.

FIFO describes storage order, but the Distributor asks for a matching request when capacity appears. An idle Chrome slot does not satisfy an older Firefox-only request. Compatibility-aware analysis is therefore essential whenever queue depth and global free slots seem contradictory.

Keep every option and unit distinct

The official Grid CLI options define the controls precisely:

Do not copy a number between these fields. A value that is modest in milliseconds is radically different in seconds. Review rendered configuration and startup logs so a unit mistake is visible before load reaches the Grid.

session-timeout under the Node is unrelated: it reclaims an existing session after inactivity. Page-load, script, and element waits are client or WebDriver command concerns. Give each timeout a name in metrics and incident reports.

Establish one measured TOML baseline

Use one baseline per Grid environment and change one dimension per experiment. The values below are illustrative integers chosen to show valid structure and relative scale, not a universal recommendation.

[sessionqueue]
session-request-timeout = 180
session-request-timeout-period = 5
session-retry-interval = 50
sessionqueue-batch-size = 12
maximum-response-delay = 4

Start by measuring steady state, a representative burst, and an intentionally unsupported capability. Record queue age, queue size, time to first assignment, session creation duration, success or rejection, Node selection, browser type, and client outcome. The unsupported request proves that the timeout and diagnostic path work; it should not silently become a long-lived CI hang.

Keep the config checksum with each run. Without it, a before-and-after graph cannot prove which queue policy produced the observation.

Set request timeout from the caller's budget

The queue timeout should fit inside the CI job's setup budget while allowing expected burst and browser-start behavior. Separate queue wait from browser creation because a request can leave the queue and still spend time starting a driver or dynamic container. The client HTTP timeout must allow Grid to return the intended response.

If the client gives up first, Grid may continue processing the request. A browser session can then exist without an owning test, consuming capacity until cleanup. If Grid expires far earlier than the caller expects, valid burst traffic fails while the job still has time available. Align the boundaries and capture which one fired.

Do not solve unsupported capabilities with a longer timeout. Enable immediate unsupported-capability rejection only when the Grid model is static enough for that policy, as documented for the Distributor. Dynamic infrastructure that can add Nodes on demand may need a different decision.

Tune retry interval for responsiveness and churn

When all compatible slots are busy, the retry interval controls when the request is reconsidered. A very short interval can increase queue and Distributor activity without freeing capacity. A long interval can leave a newly released compatible slot idle until the next retry.

Measure slot-release-to-assignment delay alongside scheduler CPU and request churn. The right value depends on session duration, release frequency, Grid size, and the cost of matching. Short smoke sessions and long end-to-end sessions create different opportunities for reassignment.

Changing retry interval does not alter FIFO arrival or capability matching. If one browser group is permanently saturated, a faster retry merely asks the same capacity question more often.

Coordinate batch size with creation concurrency

sessionqueue-batch-size bounds the number of requests consumed in one poll according to available slots. The Distributor also has a new-session creation thread pool. A large queue batch with many newly free slots can create a startup wave that stresses Distributor threads, Nodes, registries, browser hosts, and the application under test.

A tiny batch may underfill capacity after a scale-out event. Increase only while measuring queue drain, creation latency, failure rate, CPU, memory, and downstream service health. Dynamic Docker or Kubernetes sessions make startup pressure particularly visible because assignment launches infrastructure rather than reusing an already-running driver service.

Do not set batch size from total configured slots alone. Draining, unavailable, occupied, and incompatible slots reduce what can actually accept the current requests.

Treat timeout checking as a control-plane cadence

The timeout-period option controls how often the queue checks request age. It does not change the configured maximum age itself, but observed rejection timing is influenced by periodic checking and system load. Tight checking can create unnecessary work on a large busy queue; loose checking makes expiry less prompt.

Track expired-request age at rejection, not just the count. If actual age consistently exceeds policy, inspect queue health, component load, long-poll behavior, and clock consistency before lowering the check period.

maximum-response-delay affects how an empty queue responds to polling components and is available through configuration rather than a CLI flag. Treat it as an internal polling control, not a user-facing session timeout.

Separate saturation from capability mismatch

Use GraphQL to observe sessionQueueSize, active sessions, global maximum, Node statuses, and stereotypes. Global headroom plus a nonzero queue is not enough to identify a fault. Inspect whether queued capabilities have a compatible free slot on an UP Node.

Common mismatch causes include exact browser versions absent from stereotypes, platform spelling, required custom capabilities omitted by clients, vendor options attached to the wrong browser, and a Node in DRAINING state. Fixing the contract clears the queue more effectively than tuning retry cadence.

The official Grid endpoints guide documents an administrative endpoint to inspect current queue requests. Those payloads can contain sensitive capabilities, so restrict access, query only during diagnosis, and redact before retention.

Run controlled burst experiments

Create a small deterministic session fixture that starts, executes one browser command, and quits. Drive it with the same browser mix as production, then test increasing burst shapes without changing application assertions. Include one incompatible request and one intentionally slow-starting environment if those cases exist operationally.

For each attempt, record client submit time, queue admission, assignment, session response, first command, quit, and final slot release. Compare medians and tail behavior without publishing invented universal targets. The objective is to satisfy the team's own setup objective while preserving Grid and Node health.

Repeat after browser image, Node size, network, or Grid release changes. Queue tuning is coupled to session creation behavior, so yesterday's values are hypotheses after an infrastructure change.

Avoid duplicate sessions from client retries

POST /session creates state and is not safely idempotent. A client-side timeout does not prove Grid abandoned the request. Retrying immediately can create two sessions, one of which the test never learns to delete.

Prefer a client timeout that allows Grid's queue policy to answer. When transport loss makes the outcome unknown, reconcile through Grid operations and unique safe request metadata before retrying. Enforce session limits per test identity where the platform supports it, and alert on sessions with no corresponding live test worker.

Do not clear the whole queue as routine recovery. The documented DELETE queue endpoint is an administrative maintenance action and can reject unrelated pending work. Protect it with the registration secret and an explicit incident procedure.

Diagnose queue failures by evidence

A request that reaches its queue timeout needs its age, requested capabilities, matching-slot inventory, and Node statuses. A queue that drains slowly despite compatible free slots needs Distributor polling, batch, retry, thread-pool, and component-health evidence. A queue that refills as fast as it drains may simply reflect sustained demand above capacity.

If clients report timeouts but Grid shows created orphan sessions, align client and queue budgets and inspect lost responses. If expired requests remain visible too long, inspect timeout-check cadence and queue load. If one browser waits while others flow, break every metric down by stereotype before scaling the whole Grid.

Session queue tuning checklist

• Keep seconds, milliseconds, request counts, and polling cadence explicit.
• Separate queue wait, browser creation, client HTTP, and Node inactivity timeouts.
• Derive request timeout from measured startup and CI cancellation budgets.
• Measure retry responsiveness together with scheduler activity.
• Coordinate batch size with Distributor creation threads and Node startup load.
• Analyze free compatible capacity, not only global free capacity.
• Include unsupported requests in staging to prove failure behavior.
• Record config checksum and lifecycle timestamps for every experiment.
• Reconcile unknown session-creation outcomes before client retries.
• Restrict raw queue payload and administrative endpoint access.
• Retest after Grid, browser image, topology, or host changes.

Tune for bounded waiting, not hidden overload

The queue is healthy when valid bursts receive compatible capacity within the setup objective, impossible requests fail with useful evidence, and overload does not destabilize the control plane. Preserve the documented units, change one control at a time, and measure the whole path from submission through slot release. Queue settings should make capacity limits predictable, never disguise them.