Debug SessionNotCreatedException Across Selenium Manager and Grid

SessionNotCreatedException is a startup failure, not a test-step failure. The browser session never became usable, so changing element waits or rerunning an assertion cannot address it. Debug the new-session transaction from the client outward and identify the last component that completed its responsibility.

The efficient question is not simply whether the driver and browser are compatible. It is which resolver, process, protocol endpoint, or Grid allocator rejected the request, and what exact inputs that boundary received.

Locate the Failed New-Session Boundary

The Selenium error guide places this exception at session creation. For a local ChromeDriver, construction can involve Selenium binding code, Selenium Manager, a native driver service, and the browser process. For RemoteWebDriver, the client sends a new-session request to a remote endpoint; Grid then queues and assigns it before a Node starts its own driver and browser.

Record the last visible success. If Manager never resolves an executable, investigate discovery, cache, permissions, proxy, or network policy. If the driver service starts and returns a structured session not created error, inspect browser launch and capability evidence. If Grid accepts a request but it expires in the queue, investigate matching and capacity rather than the developer machine.

Separate Resolution from Browser Launch

Selenium Manager resolves drivers when the binding does not already have one. That makes resolution a distinct phase. A missing or unwritable cache, blocked vendor endpoint, proxy rejection, unexpected executable in PATH, or wrong browser path can stop the flow before the native driver listens. The official Selenium Manager documentation describes its discovery, download, cache, and configuration order.

Do not infer which binary was chosen from a filename. Capture the absolute browser path, absolute driver path, operating system, architecture, and process user from the same worker that failed. Interactive shells and CI services often have different PATH, home directories, proxies, mounts, and permissions. A successful command in a developer terminal proves little about a containerized job.

Also distinguish an inability to locate a driver from an inability to create a session. Selenium's driver location troubleshooting page covers the former. Once a driver process is listening and answers the new-session request, the investigation has moved to launch or negotiation.

Turn On Manager Diagnostics Deliberately

Manager can emit debug or trace diagnostics through its configuration. Enable that output for a controlled failing run, store it with the test attempt, and return normal jobs to their quieter policy. Diagnostics can reveal discovered paths, cache decisions, network requests, and selected artifacts, but they may also expose internal locations or proxy details.

Selenium Manager configuration (se-config.toml):

debug = true
cache-path = "/opt/selenium-cache"
offline = true

This example is appropriate only for a worker whose cache is deliberately pre-provisioned. offline = true is not a generic repair for network errors; it forbids downloads and therefore requires the needed metadata and binaries to be present. Environment keys such as SE_DEBUG follow the official naming rules, but configuration precedence matters. Log which layer supplied a value so a stale machine-level setting does not masquerade as a binding defect.

Inspect the Native Driver Service Next

When Manager succeeds, the binding starts a browser-specific driver service. Preserve that service's output before teardown. A bind failure, executable permission error, missing runtime dependency, profile lock, invalid browser argument, or browser crash belongs to this phase. A blank service log suggests failure before process startup or an unwritable destination; a listening service followed by an error response proves the request reached the driver.

Give each parallel attempt a unique log path. One shared append file destroys ordering and can pair a request from one worker with a launch error from another. The artifact record should connect test ID, worker ID, service log, requested options, and exception without relying on timestamps alone.

Do not automatically delete a user-data directory or shared cache to make the next run pass. That can erase the evidence and conceal an ownership error. Use a fresh test-owned profile for the reproduction, then separately repair cache permissions or lifecycle policy.

Compare Actual Browser and Driver Inputs

A browser-driver mismatch is common, but the durable fix is provenance, not a hard-coded version guess. Determine which browser binary actually launched and which driver executable actually answered. Look for multiple installations, symlinks, image layers, auto-updated host browsers, restored caches, and explicit options that select a non-default binary.

Treat a compatibility message as evidence from the driver, then inspect deployment inputs. If CI promotes browser and driver artifacts together, record their checksums or immutable image identity. If Selenium Manager owns resolution, make its cache and network policy explicit. Mixing a manually pinned driver, a silently updating browser, and an old shared cache creates three independent owners for one compatibility contract.

Never make a disabled compatibility check the standing solution. It converts an early, explainable startup rejection into undefined behavior during later commands. Restore a supported artifact pair instead.

Validate Capabilities Before Blaming Binaries

The new-session payload can fail even when the processes are healthy. Standard capabilities may contain an unsupported platform or browser constraint. Vendor namespaces may hold malformed arguments, an unavailable binary path, an invalid profile, or mutually incompatible startup switches. On Grid, a valid request may still match no stereotype.

Build options through Selenium's typed classes and archive a redacted rendering of the request. Remove credentials, proxy secrets, profile content, and provider tokens. Then reduce the failing request: start with browser name and essential environment requirements, establish a session, and add options back by responsibility. This is controlled isolation, not random deletion.

Java (local capability isolation):

ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new", "--window-size=1280,800");

WebDriver driver = new ChromeDriver(options);
try {
  driver.get("https://test.example/health");
} finally {
  driver.quit();
}

If the minimal session succeeds, compare only the removed options. If it fails before a driver service starts, return to resolution. If the service rejects it, preserve the response and native log rather than broadening a timeout.

Debug Grid as a Separate Failure Domain

For remote execution, first prove that the client reached the intended Grid URL. Then correlate Router, New Session Queue, Distributor, and Node evidence. A queued request with no compatible slot is not a local Selenium Manager problem because driver resolution occurs on the selected Node, which has not yet been selected. A request assigned to a Node and then rejected during launch is a node-side process problem.

Compare the exact requested capabilities with live slot stereotypes, including namespaced custom capabilities. Check Node status and available slots, not merely whether a Node process exists. A registered Node can be unavailable, saturated, draining, or advertising a stereotype that differs in case, value type, platform, or browser identity.

Capture a Grid request correlation value when the deployment exposes one. Without it, use a narrow time window plus client identity and redacted capabilities. Do not diagnose a busy distributed Grid from one client stack trace alone.

Make Retries Conditional on Classification

A retry is justified after a transient dependency changed: a replacement Node registered, a capacity slot became free, a short control-plane interruption recovered, or a test-owned process cleanup completed. Put a small bound around that retry and retain both attempts. The first failure is the evidence; the second confirms whether recovery worked.

Do not retry invalid arguments, impossible stereotypes, missing executables, or deterministic compatibility errors. Those failures consume queue capacity and delay useful work. Classify them as configuration defects and fail promptly with the resolved paths and request summary attached.

Avoid deleting the global Manager cache on every failure. A clean-room reproduction can use an isolated cache directory, while the original cache is retained for inspection. This preserves the distinction between corrupt state and an unavailable download source.

Close with a Reproducible Startup Contract

The lasting repair is a startup contract that names every owner: the binding owns request construction, Manager or the build owns artifact resolution, the service fixture owns the native process, Grid owns assignment, and the Node owns remote browser launch. Record the output of each owner at its boundary.

When SessionNotCreatedException appears again, start at the failed new-session transaction, not at the test method. Prove resolution, prove service startup, prove browser and driver provenance, prove capability validity, and prove Grid matching. Retry only after one of those facts changes. That path turns an opaque constructor failure into a finite operational diagnosis.