{"record":{"id":"b5b67817c7b3fdb9","repo":"karatelabs/karate","slug":"driver-not-configured-use-configure-driver-type-chrome","errorCode":null,"errorMessage":"driver not configured - use: * configure driver = { type: 'chrome' }","messagePattern":"driver not configured - use: \\* configure driver = (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/ScenarioRuntime.java","lineNumber":2150,"sourceCode":"        // runtime; release it back to the pool before re-init or the slot leaks and subsequent\n        // grid-style runs (multiple browsers per scenario) deadlock once the pool fills\n        if (driver != null && driver.isTerminated()) {\n            closeDriver();\n        }\n        if (driver == null) {\n            driver = initDriver();\n        }\n        return driver;\n    }\n\n    /**\n     * Initialize the browser driver from configuration.\n     */\n    @SuppressWarnings(\"unchecked\")\n    private Driver initDriver() {\n        Object driverConfig = config.getDriverConfig();\n        if (driverConfig == null) {\n            throw new RuntimeException(\"driver not configured - use: * configure driver = { type: 'chrome' }\");\n        }\n\n        Map<String, Object> configMap = null;\n        if (driverConfig instanceof Map) {\n            configMap = new java.util.HashMap<>((Map<String, Object>) driverConfig);\n        } else {\n            configMap = new java.util.HashMap<>();\n        }\n\n        // Check if a driver provider is configured at Suite level\n        io.karatelabs.driver.DriverProvider provider = null;\n        if (featureRuntime != null && featureRuntime.getSuite() != null) {\n            provider = featureRuntime.getSuite().getDriverProvider();\n            // Default userDataDir to <buildDir>/karate-temp/chrome-<uuid> if not explicitly set\n            // Uses buildDir (target or build) as sibling to karate-reports, not inside it\n            if (!configMap.containsKey(\"userDataDir\")) {\n                java.nio.file.Path tempDir = java.nio.file.Path.of(\n                        io.karatelabs.common.FileUtils.getBuildDir(),","sourceCodeStart":2132,"sourceCodeEnd":2168,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/ScenarioRuntime.java#L2132-L2168","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\n* driver 'https://example.com'   // throws\n// after\n* configure driver = { type: 'chrome' }\n* driver 'https://example.com'","handlingStrategy":"validation","validationCode":"// in karate-config.js\nif (!config.driver && needsBrowser) { config.driver = { type: 'chrome' }; }","typeGuard":null,"tryCatchPattern":"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; }","preventionTips":["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"],"tags":["driver","browser","configuration"],"backgroundTag":"missing-required-config","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-16T19:17:19.609Z"}