karatelabs/karate · error · RuntimeException

driver not configured - use: * configure driver =

Error message

driver not configured - use: * configure driver = { type: 'chrome' }

What it means

Before a scenario can drive a browser, ScenarioRuntime.initDriver() reads the `driver` configuration. If configure driver was never set, config.getDriverConfig() is null and the runtime throws this explicit message telling the user how to fix it.

Solutions

Add `* configure driver = { type: 'chrome' }` (or desired type) in the feature or karate-config.js before the first driver keyword
Set it globally in karate-config.js, e.g. `configurator.configure('driver', { type: 'chrome', showProcessLog: true })`
Run with the correct karate.env so the config block that sets driver actually executes

Example fix

// before
* driver 'https://example.com'   // throws
// after
* configure driver = { type: 'chrome' }
* driver 'https://example.com'

Defensive patterns

Strategy: validation

Validate before calling

// in karate-config.js
if (!config.driver && needsBrowser) { config.driver = { type: 'chrome' }; }

Try / catch

try { karate.driver('https://example.com'); } catch (RuntimeException e) { if (e.getMessage().startsWith("driver not configured")) { fail("add * configure driver = { type: 'chrome' } before browser steps"); } throw e; }

Prevention

Always set `configure driver` in karate-config.js for UI projects, not per-feature
Verify the active karate.env branch actually assigns the driver config
Never call driver keywords in API-only features copied from UI tests

When it happens

Trigger: Any driver keyword (driver 'url', click, input, etc.) or Driver instantiation when no `configure driver = {...}` was executed in the feature, calling feature, karate-config.js, or caller scope.

Common situations: New UI test projects missing the driver config; config only defined in an env-specific branch of karate-config.js that is skipped because -Dkarate.env doesn't match; calling browser keywords in an API-only feature copied from a UI test; configuring driver inside a Scenario that runs after the one using it.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/b5b67817c7b3fdb9. Report an issue: GitHub.

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/ScenarioRuntime.java:2150

        // runtime; release it back to the pool before re-init or the slot leaks and subsequent
        // grid-style runs (multiple browsers per scenario) deadlock once the pool fills
        if (driver != null && driver.isTerminated()) {
            closeDriver();
        }
        if (driver == null) {
            driver = initDriver();
        }
        return driver;
    }

    /**
     * Initialize the browser driver from configuration.
     */
    @SuppressWarnings("unchecked")
    private Driver initDriver() {
        Object driverConfig = config.getDriverConfig();
        if (driverConfig == null) {
            throw new RuntimeException("driver not configured - use: * configure driver = { type: 'chrome' }");
        }

        Map<String, Object> configMap = null;
        if (driverConfig instanceof Map) {
            configMap = new java.util.HashMap<>((Map<String, Object>) driverConfig);
        } else {
            configMap = new java.util.HashMap<>();
        }

        // Check if a driver provider is configured at Suite level
        io.karatelabs.driver.DriverProvider provider = null;
        if (featureRuntime != null && featureRuntime.getSuite() != null) {
            provider = featureRuntime.getSuite().getDriverProvider();
            // Default userDataDir to <buildDir>/karate-temp/chrome-<uuid> if not explicitly set
            // Uses buildDir (target or build) as sibling to karate-reports, not inside it
            if (!configMap.containsKey("userDataDir")) {
                java.nio.file.Path tempDir = java.nio.file.Path.of(
                        io.karatelabs.common.FileUtils.getBuildDir(),

View on GitHub (pinned to a22eb90246)