karatelabs/karate · critical · RuntimeException

chrome executable not found. Set 'executable' option…

Error message

chrome executable not found. Set 'executable' option, KARATE_CHROME_EXECUTABLE env var, or install Chrome at: ${defaultPath}

What it means

resolveExecutable tries, in order: the configured 'executable' option, the KARATE_CHROME_EXECUTABLE env var, then platform-specific default Chrome install paths. If none exists or is executable, it throws this RuntimeException telling you exactly which knob to set.

Solutions

1. Set KARATE_CHROME_EXECUTABLE to the absolute path of your Chrome/Chromium binary
2. Set the 'executable' option in the karate driver config
3. Install Chrome (or Chromium) at the platform default location named in the error message
4. In Docker, install chromium in the image and point executable at /usr/bin/chromium

Example fix

// before
defaults with no executable configured
// after (karate config)
configured: { type: 'chrome', executable: '/usr/bin/chromium-browser' }

String chrome = System.getenv("KARATE_CHROME_EXECUTABLE");
if (chrome == null || !new File(chrome).canExecute()) {
    throw new IllegalStateException("set KARATE_CHROME_EXECUTABLE to a runnable chrome binary");
}

boolean chromeAvailable(String path) {
    return path != null && new File(path).isFile() && new File(path).canExecute();
}

try {
    CdpLauncher.start(options);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("chrome executable not found")) {
        options.setExecutable("/usr/bin/chromium-browser");
        CdpLauncher.start(options);
    } else throw e;
}

When it happens

Trigger: Launching the CDP driver on a machine with no Chrome installed at any default path, no env var set, and no 'executable' option in the driver config.

Common situations: Fresh CI container or Docker image without a browser; Linux server where Chrome is at a nonstandard path; macOS/Windows where the user deleted or upgraded Chrome and the default path changed; teammates with different OSes sharing one config.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• configured executable not found
• at least one feature file is required
• boot.classpath(' '): expected a directory RELATIVE to the…
• boot.classpath: dir is null — pass a project-relative…
• boot.read: path is null

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/cdp/CdpLauncher.java:156

        }
        return fetchWebSocketUrl(host, port);
    }

    private static String resolveExecutable(String configured) {
        if (configured != null && !configured.isEmpty()) {
            if (Files.isExecutable(Path.of(configured))) {
                return configured;
            }
            logger.warn("configured executable not found: {}", configured);
        }

        String defaultPath = getDefaultPath();
        if (defaultPath != null && Files.isExecutable(Path.of(defaultPath))) {
            logger.debug("using default chrome path: {}", defaultPath);
            return defaultPath;
        }

        throw new RuntimeException("chrome executable not found. " +
                "Set 'executable' option, KARATE_CHROME_EXECUTABLE env var, " +
                "or install Chrome at: " + defaultPath);
    }

    private static String getDefaultPath() {
        if (OsUtils.isMac()) {
            return DEFAULT_PATH_MAC;
        } else if (OsUtils.isWindows()) {
            // Prefer 64-bit, fall back to 32-bit
            if (Files.isRegularFile(Path.of(DEFAULT_PATH_WIN64)) &&
                    Files.isReadable(Path.of(DEFAULT_PATH_WIN64))) {
                return DEFAULT_PATH_WIN64;
            }
            return DEFAULT_PATH_WIN32;
        } else if (OsUtils.isLinux()) {
            return DEFAULT_PATH_LINUX;
        }
        return null;

View on GitHub (pinned to a22eb90246)