FAQ and common problems

This page collects common pitfalls and their solutions. If you run into something not listed here, turn on debug logging and check the error category and hint:

Start here#

Detected as a bot despite UC mode#

UC mode removes many fingerprints, but detection is layered. Check each defense:

chromedriver executable not found#

BaseCase::new starts a chromedriver for you when the WebDriver URL is the default (http://localhost:4444) and auto_start_driver is on (it is by default).

How BaseCase::new finds or starts a chromedriver

BaseCase::new first tries to connect to a driver already listening there; if none answers, it launches downloaded_drivers/chromedriver (chromedriver.exe on Windows) on a free port. A chromedriver only drives the Chrome of its own major version, so before launching it the crate runs --version on the driver and on your Chrome. If the driver is missing, or is for another major version, it downloads the driver of your Chrome’s milestone into downloaded_drivers/ first (the latest stable one when Chrome cannot be found). If both downloads fail it keeps the old driver and logs a warning. The download needs network access to the Chrome for Testing endpoint. To fetch the driver ahead of time:

cargo run --bin sbrs -- install

sbrs install with no argument fetches chromedriver; sbrs install geckodriver and sbrs install edgedriver fetch the drivers of Firefox and Edge (see the CLI page).

To use a driver you run yourself, start it and pass its URL. A URL other than the default turns auto-start off:

chromedriver --port=9515 &cargo run --bin sbrs -- --webdriver http://localhost:9515 open https://example.com

A driver you start yourself and pass with --webdriver is never replaced. If it does not match your Chrome version, the session fails to start with a WebDriver error; sbrs doctor shows both versions, and sbrs install or the Chrome for Testing dashboard has a matching one.

chromedriver is killed or refused on macOS#

macOS can refuse a driver that has the com.apple.quarantine flag or whose code signature no longer matches its contents (which is what patching does). The crate repairs this itself: after downloading, and again if the system refuses to start the driver, it adds the execute permission, removes the quarantine flag and, for a binary the system killed as it started, signs it again ad hoc (codesign --force --sign -). ChromedriverPatcher::patch also signs the patched file again on macOS. The same repair is available as seleniumbase_rs::browser::driver_access::make_runnable(path, resign). If a driver you supply still will not start, run the two steps by hand:

xattr -d com.apple.quarantine /path/to/chromedrivercodesign --force --sign - /path/to/chromedriver

Headless detected#

BrowserConfig::default() is headless, while the global config file and the sbrs command line default to headed. A headless session passes --headless=new (and --disable-gpu) to Chrome. Switch to headed mode for sites that still refuse it:

use seleniumbase_rs::{BrowserConfig, DriverMode};let config = BrowserConfig::default()    .with_mode(DriverMode::Uc)    .with_headless(false);

Combine this with a Fingerprint and binary patching. On a server with no display, run the headed browser under a virtual display such as Xvfb. The defaults of every entry point and what gives a headless browser away are in Headless and headed browsers.

Item not found: a Cargo feature is off#

Nothing is enabled by default. These pieces exist only when their feature is on:

Enable one with --features, for example cargo build --features tui,turso.

Playwright / rustwright feature not compiling#

The playwright feature pulls in the rustwright and rustwright-core crates from crates.io, which bring a large Chromium automation core. It is off by default, so a plain cargo build does not need them:

cargo build --features playwright

The project’s own quality gate (see ROADMAP.md) notes that building with --all-features needs a libpython available because of this feature. If you build with it on macOS and a test binary fails to start with a missing libpython...dylib, point the loader at your Python install’s lib folder:

DYLD_LIBRARY_PATH=/path/to/python/lib cargo test --features playwright

MCP server not listing tools#

The sbrs-mcp binary only exists when the mcp-server feature is enabled:

cargo build --bin sbrs-mcp --features mcp-server

The server communicates over stdio. Configure your MCP client with the absolute path to the built binary. It serves the sb toolset unless you pass --server cdp or --server driver. Listing tools does not require a running browser, but no browser exists until the client calls the start_browser tool; any other browser tool called first returns “no browser session is running; call start_browser first”. See the MCP servers guide.

Macro not found#

Macros are #[macro_export] and live at the crate root, not under seleniumbase_rs::macros:

use seleniumbase_rs::{sb_open, sb_click, sb_test, selector};

Action macros expand .await internally, so they must be called inside an async block or function. sb_test! generates a #[tokio::test] wrapper for you. See the macros guide.

Chrome is not found#

The library looks in the usual install locations for your system (see Operating systems). If yours is elsewhere, or you want a specific build, name it:

export SB_CHROME_BIN="/path/to/chrome"      # CHROME_BIN also works

Run sbrs doctor to confirm which one was picked. The pure CDP engine also takes the path in LaunchOptions.

Chrome will not start in a container#

Chrome often cannot start its sandbox as root or inside Docker. Set SB_NO_SANDBOX=1 (or LaunchOptionsBuilder::no_sandbox(true) in the pure CDP engine) and run headless (SB_HEADLESS=true).

If it crashes under load rather than at start, give the container more shared memory (--shm-size=1g). See Deployment.

An element is not found or a wait times out#

Read the error before changing anything: it names the selector and carries a hint, and element errors point out a likely mistake in the selector.

Passes alone, fails in the suite#

The usual causes are shared state and too much parallelism. Give each test its own browser context (the pool’s Lease isolates cookies and storage), do not reuse a logged-in profile between tests, and lower SB_THREADS to see whether the failure goes away. Do not add retries to hide it; see Reliability.

Reading an error#

Every SeleniumBaseError has a hint: the likely cause and the fix (error.hint()). Element errors name the selector, the strategy it was read as (the same rules the lookup uses), and a likely mistake in it: a mistyped prefix (lnk=Home for link=Home), a prefix from another tool (css=, xpath=, id=, name=), XPath without its leading //, or unbalanced brackets.

sbrs prints a failure for people, on standard error, with colour only on a terminal (and never with NO_COLOR set):

error: invalid configuration: failed to read settings: No such file or directory (os error 2)hint: Review the configuration values passed to the builder, the command line or the environment; `sbrs doctor` checks the browser setup.

A cause the first line does not already say gets its own caused by: line. The exit status says which kind of failure it was:

In the HTML report of ReportPlugin, a failed test shows its error, the hint, the page’s URL and title when it failed, and, with ReportPlugin::html(path).with_evidence(), links to the screenshot and page source saved next to the report. The MCP servers answer a failed call with a report that includes the page’s state and the next tools to try; see the MCP tutorial.

Errors are not descriptive enough#

SeleniumBaseError::log() emits a tracing error event with the error category, whether it is transient, and a remediation hint; ResultExt::log_err logs only the message. Make sure a subscriber is installed:

# use seleniumbase_rs::{init_tracing, BaseCase, ResultExt};# async fn demo(case: &mut BaseCase) {init_tracing();// `log_err` logs the message and returns the Result unchanged.let _ = case.click("#missing").await.log_err();// `log` adds `error.category`, `error.transient` and `error.hint` fields.if let Err(err) = case.click("#missing").await {    err.log();}# }

Or configure the log level before running sbrs / sbrs-mcp:

SB_LOG_LEVEL=seleniumbase_rs=info,error cargo run --bin sbrs -- open https://example.com

SeleniumBaseError provides helpers for programmatic handling:

# use seleniumbase_rs::SeleniumBaseError;# fn handle(err: SeleniumBaseError) -> Result<(), SeleniumBaseError> {match err {    e if e.is_transient() => println!("worth another attempt: {e}"),    e if e.is_skipped() => return Ok(()),    e if e.category() == "element_not_found" => {        println!("Hint: {}", e.hint().unwrap_or_default());    }    e => return Err(e),}# Ok(())# }

To retry transient failures with backoff, see RetryPolicy in the reliability guide.

Environment variable not applied#

Configuration uses the SB_ prefix, not SBASE_. For example:

export SB_HEADLESS=trueexport SB_WEBDRIVER_URL=http://localhost:9515

Where a variable is read depends on how you build the configuration:

• BrowserConfig::default() reads no variables. BrowserConfig::from_env() reads the runtime ones (SB_WEBDRIVER_URL, SB_CHROME_BIN, SB_REMOTE_WEBDRIVER_TIMEOUT, and so on).
• Settings::load(), Settings::load_from(path) and Settings::from_env() read the settings ones, SB_WEBDRIVER_URL and SB_CHROME_BIN among them (SB_BROWSER, SB_HEADLESS, SB_TIMEOUT, and the rest of the list in Customizing Test Runs). sbrs test passes the flags you give it to the tests as such variables.
• The sbrs binary reads the settings ones. Its browser commands (open, smoke, and the rest) start from the config file (--config FILE, else the global one), apply the settings variables on top, and then its own flags, which win. The WebDriver URL is --webdriver, else SB_WEBDRIVER_URL, else http://localhost:4444; the browser binary is SB_CHROME_BIN.

See Customizing Test Runs for the full list.

Frequently asked questions#

Short answers, with a pointer to the page that has the detail.

Choosing and getting started#

Using it#

Browsers and drivers#

Stealth and scraping#

Contributing and project status#