What causes "options cannot be null" in karatelabs/karate?

Construct a CdpDriverOptions (or build it from your karate driver config) before calling start()

karatelabs/karate · error · IllegalArgumentException

options cannot be null

Error message

options cannot be null

What it means

CdpLauncher.start() requires a CdpDriverOptions object to know which Chrome executable, port, and host to use. This is a fail-fast precondition check: null options would cause an NPE deeper inside launch logic. The library throws IllegalArgumentException immediately so the caller knows the configuration object itself is missing.

Solutions

Construct a CdpDriverOptions (or build it from your karate driver config) before calling start()
Null-check / default the options object at the call site before invoking CdpLauncher.start
If using Karate's driver layer, ensure the driver config actually selects the chrome/cdp driver so options are auto-created

Example fix

// before
CdpLauncher launcher = CdpLauncher.start(null);
// after
CdpDriverOptions options = new CdpDriverOptions();
options.setExecutable("/usr/bin/google-chrome");
CdpLauncher launcher = CdpLauncher.start(options);

Defensive patterns

Strategy: validation

Validate before calling

if (options == null) {
    options = new CdpDriverOptions(); // or load from config
}
CdpLauncher.start(options);

Type guard

boolean optionsReady(CdpDriverOptions o) { return o != null; }

Try / catch

try {
    CdpLauncher.start(options);
} catch (IllegalArgumentException e) {
    // options was null — build defaults and retry once
    CdpLauncher.start(new CdpDriverOptions());
}

Prevention

Build CdpDriverOptions in one factory method so it is never conditionally null
Never pass nullable option objects into launchers
Initialize driver options from karate config at startup, not lazily

When it happens

Trigger: Calling CdpLauncher.start(null) directly, or a driver bootstrap path that constructs the CDP launcher without first building a CdpDriverOptions from config.

Common situations: Programmatic launcher use where options are conditionally built and a branch leaves them unset; refactoring code that previously read config into options; tests that pass null to shortcut configuration.

Related errors

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

Appendix: source

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

        this.process = process;
        this.host = host;
        this.port = port;
        ACTIVE.add(this);
    }

    /**
     * Close all active browser instances.
     */
    public static void closeAll() {
        ACTIVE.forEach(CdpLauncher::close);
    }

    /**
     * Launch Chrome browser and return launcher instance.
     */
    public static CdpLauncher start(CdpDriverOptions options) {
        if (options == null) {
            throw new IllegalArgumentException("options cannot be null");
        }

        String executable = resolveExecutable(options.getExecutable());
        int port = options.getPort() > 0 ? options.getPort() : PortUtils.findFreePort();
        String host = options.getHost();
        if (host == null || host.isEmpty()) {
            host = "localhost";
        }

        // Ensure timeout is reasonable (minimum 1 second)
        int timeout = Math.max(options.getTimeout(), 1000);

        List<String> args = buildArgs(executable, port, options);
        logger.debug("launching chrome: {}", args);

        ProcessHandle process = ProcessHandle.start(
                ProcessBuilder.create()
                        .args(args)

View on GitHub (pinned to a22eb90246)