karatelabs/karate · warning

invalid karate.options ignored

Error message

invalid karate.options ignored: {}

What it means

The `karate.options` system property string is tokenized into CLI arguments and parsed with the RunCommand CLI grammar. When picocli's CommandLine.parseArgs throws a ParameterException (unknown option, missing value, bad number, etc.), the whole options string is discarded with this warning and the run continues with the defaults (builder paths/tags and the given threadCount) — the invalid options are silently not applied.

Solutions

  1. Run the same string through the CLI (or locally validate it) and fix the offending option/typo — the warning's `{}` payload is the picocli ParameterException message naming the exact bad argument.
  2. Remove or correct the v1-only flags; check the v2 RunCommand supported options for equivalents.
  3. Quote/escape the options string properly for the shell or Maven/Surefire argLine so tokens tokenize as intended.
  4. If the warning is expected/acceptable, ignore it — the run proceeds with defaults; otherwise set options programmatically via Runner.Builder instead of the system property.

Example fix

// before (bad: value missing for -t, flag unknown)
System.setProperty("karate.options", "-t @smoke --out target");
// after
System.setProperty("karate.options", "-t @smoke -o target");
Defensive patterns

Strategy: validation

Validate before calling

String raw = System.getProperty("karate.options");
if (raw != null) {
    List<String> tokens = io.karatelabs.core.ProcessBuilder.tokenize(raw);
    for (String t : tokens) {
        if (t.startsWith("-") && !t.matches("-t|-T|--tags|--env|--threads|-o|--output|--configdir|-f|--format|-n|--name|--dryrun|-P|--path")) {
            throw new IllegalArgumentException("unsupported karate.options token: " + t);
        }
    }
}

Prevention

When it happens

Trigger: Setting the `karate.options` system property to a string that fails CLI parsing, e.g. `-Dkarate.options="-t@tag -t"` (missing value), `--threads=abc` (non-numeric), or an unknown flag like `--out=x`, when Runner/apply() invokes parseAndApplyOptions.

Common situations: Typo in an option name; copying v1-only flags that the v2 RunCommand grammar no longer supports; shell quoting issues that split or merge tokens (quotes stripped/kept incorrectly); forgetting that a value-taking flag like `-t` or `--env` needs its argument.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/KarateOptionsHandler.java:168

                logger.debug("karate.config.dir override: '{}' (Builder) -> '{}' ({})",
                        builder.getConfigDir(), value, source);
            }
            builder.setConfigDir(value);
        }
    }

    /**
     * Parse the options string using the v2 CLI grammar and apply it to the Builder.
     * Package-private for direct testing.
     */
    static int parseAndApplyOptions(Runner.Builder builder, String raw, int threadCount) {
        List<String> tokens = ProcessBuilder.tokenize(raw);
        String[] argv = tokens.toArray(new String[0]);
        RunCommand parsed = new RunCommand();
        try {
            new CommandLine(parsed).parseArgs(argv);
        } catch (CommandLine.ParameterException e) {
            logger.warn("invalid karate.options ignored: {}", e.getMessage());
            return threadCount;
        }

        // Collect applied summary for the INFO line
        List<String> summary = new ArrayList<>();

        // --- Paths (positional + -P) — REPLACE (v1 parity) ---
        List<String> combinedPaths = new ArrayList<>();
        if (parsed.getPaths() != null) combinedPaths.addAll(parsed.getPaths());
        if (parsed.getPathOptions() != null) combinedPaths.addAll(parsed.getPathOptions());
        if (!combinedPaths.isEmpty()) {
            List<String> before = new ArrayList<>(builder.getPaths());
            builder.clearPaths();
            for (String p : combinedPaths) {
                builder.path(p);
            }
            summary.add("paths=" + combinedPaths);
            if (logger.isDebugEnabled()) {

View on GitHub (pinned to a22eb90246)