skip to content

In Selenium Grid, what do the --session-request-timeout and --session-retry-interval flags each control?

level: middleimportance: should knowfreq 47%

answer

  1. Two flags, two different units
  2. One is a deadline, one a cadence
  3. Seconds for the wait, milliseconds for the poll
  4. Three hundred, and fifteen
  5. Below the floor is silently ignored

basics

~20 s

One bounds the wait, the other paces the poll. In Selenium 4, --session-request-timeout is how many seconds a request may sit in Grid's queue before failing, default 300. --session-retry-interval is how often in milliseconds the Distributor rechecks, default 15.

solid answer

~40 s

`--session-request-timeout` is a deadline: a new-session request may sit in Selenium Grid's New Session Queue for that many seconds, and when it expires the Grid answers `session not created`. It defaults to 300 seconds. `--session-retry-interval` is a cadence rather than a deadline - how often, in **milliseconds**, the Distributor wakes and checks whether any queued request can now be matched to a freed slot. In Selenium 4 it defaults to 15 milliseconds and is clamped at that floor, so a smaller value has no effect. The unit difference is the usual trap: `--session-retry-interval 2` written to mean two seconds gives two milliseconds, which is raised back to fifteen. A third setting, `--session-request-timeout-period`, defaults to 10 seconds and sets how often the queue sweeps for requests that have already expired.

code

toml · 4 lines
toml
[sessionqueue]
session-request-timeout = 600
session-request-timeout-period = 5
session-retry-interval = 50

go deeper

for a junior

Recall that Selenium Grid queues a new-session request when no slot is free, and that the wait is bounded by a configurable timeout rather than lasting forever. Knowing the flag exists is enough at this stage.

for a middle

Explain both mechanics: --session-request-timeout in seconds bounding the wait, --session-retry-interval in milliseconds pacing the Distributor's poll, with defaults 300 and 15. An interviewer expects you to catch the unit difference unprompted.

for a senior

Show judgment about the values. Say why raising the timeout only lengthens failure, why the retry interval rarely needs touching, and how you would set both in a TOML file or through the container environment variables.

for a principal

Own the policy. Argue what queue wait your organisation absorbs before a request fails, and treat that number as a service commitment to suite authors rather than a knob to raise whenever runs go red.

## The queue these flags govern Selenium Grid does not reject a new-session request because every browser is busy. It parks the request in the **New Session Queue** and answers the client only once the request has either been matched to a free **slot** or given up on. Two settings bound that behaviour, and they are routinely confused because their names rhyme and their units do not. - `--session-request-timeout` is a **deadline**, measured in **seconds**, default **300**. - `--session-retry-interval` is a **cadence**, measured in **milliseconds**, default **15**. - `--session-request-timeout-period` is a third, related setting: how often, in **seconds** (default **10**), the queue sweeps for requests that have already blown their deadline. ## The deadline: how long a request may wait Every request entering the queue is stamped with an end time - the instant it was enqueued plus `--session-request-timeout`. If a matching slot frees before then, the session starts and the client receives its session id. If it does not, the request is completed with a `SessionNotCreatedException` and the client receives the W3C `session not created` error. Raising the deadline does not add capacity. On a Grid whose slots are genuinely oversubscribed a larger value converts fast failures into slow ones, and the photo-album uploader suite's wall-clock time gets worse rather than better. Lowering it makes saturation visible sooner, at the cost of failing requests that a short burst would eventually have served. ## The cadence: how often the queue is rechecked `--session-retry-interval` is not a per-request setting at all. The **Distributor** runs a scheduled task that wakes on this interval, looks at which stereotypes currently have free capacity, and pulls the queued requests it can now match. Fifteen milliseconds is already a tight loop; the interval is small because it decides how long a freed slot sits idle before the next waiting request is noticed. Two mechanical details matter: 1. The configured value is **clamped to a floor of 15 milliseconds**. A smaller number silently leaves the cadence exactly where it was. 2. Because the unit is milliseconds, `--session-retry-interval 2` does not mean two seconds. It means two milliseconds, which is then raised to fifteen - so a team that thought it had slowed the poll down by a factor of a hundred changed nothing at all. ## The two flags side by side | | `--session-request-timeout` | `--session-retry-interval` | |---|---|---| | Unit | seconds | milliseconds | | Default | 300 | 15 | | Kind | deadline for one queued request | polling cadence for the whole queue | | Consumed by | the New Session Queue | the Distributor | | Effect of raising it | requests wait longer before failing | freed slots stay idle longer | | Effect on capacity | none | none | ## Where you set them Both live in the `[sessionqueue]` section of a Grid TOML file, under the flag name with its leading dashes removed, and both are accepted on the command line by the components that carry the session-queue role - a `standalone` or `hub`, and the `router`, `distributor` and `sessionqueue` roles in a fully distributed Grid. The official Selenium container images surface them as the environment variables `SE_SESSION_REQUEST_TIMEOUT` and `SE_SESSION_RETRY_INTERVAL`, and their start scripts translate those back into the same two flags. Choosing values for a real suite follows from what each flag is: - Leave `--session-retry-interval` alone unless you have measured a reason. The default already recovers a freed slot in well under a tenth of a second. - Set `--session-request-timeout` from the wait you are willing to absorb, not from the wait you are currently observing. It is a service commitment to the suite authors. - If the photo-album uploader suite bursts at the start of a run and then tapers, a generous deadline lets the queue smooth the burst instead of failing it. - If you would rather learn about saturation immediately, shorten the deadline deliberately and accept the failures as a signal. - Never move either flag as a reaction to red runs without first establishing whether requests are waiting because slots are busy or because nothing can ever match them. ## What neither flag does Neither setting changes how many browsers can run at once; that is decided by the slots the Nodes declare. Neither retries a *session* that started and then failed. And neither is the Node's own idle-session timeout, which is a separate setting with a separate job - conflating the queue deadline with it is the most common way these numbers get tuned in the wrong direction.

  • Where do these two settings live in a Grid TOML configuration file?
    Both sit in the `[sessionqueue]` section as `session-request-timeout` and `session-retry-interval` - the flag name with its leading dashes removed. The same section holds `session-request-timeout-period`. The official Selenium container images expose them as `SE_SESSION_REQUEST_TIMEOUT` and `SE_SESSION_RETRY_INTERVAL`, which their start scripts translate back into the flags.
  • Does raising --session-request-timeout make the photo-album uploader suite finish faster?
    No. It only lets requests wait longer before failing. On a Grid short of slots a larger value converts fast failures into slow successes or slow failures, while total throughput is unchanged, because throughput is set by how many slots exist and how long sessions hold them.
  • What is --session-request-timeout-period actually for?
    It sets how often, in seconds, the queue sweeps for requests that have outlived their deadline, defaulting to 10. It is the sweep's cadence rather than the deadline itself, so an expired request can linger briefly past its timeout before it is failed and removed from the queue.

saying these in an interview costs you the question

  • Reads --session-retry-interval as seconds and sets it to 2 expecting a two-second poll
  • Thinks --session-retry-interval bounds how long a request may wait in the queue
  • Believes a shorter retry interval creates capacity rather than only polling more often
  • Confuses the queue deadline with the Node's own separate idle-session timeout setting
  • Assumes a value below fifteen milliseconds for the retry interval takes effect