What causes "feature path is required" in karatelabs/karate?

Pass a non-empty path, e.g. new KarateFeatureBuilder("classpath:features/cats.feature")

karatelabs/karate · error · IllegalArgumentException

feature path is required

Error message

feature path is required

What it means

KarateFeatureBuilder wraps a Karate feature file for execution inside a Gatling simulation. The feature path is mandatory; constructing the builder with a null or empty string throws IllegalArgumentException immediately, before any scenario is registered.

Solutions

Pass a non-empty path, e.g. new KarateFeatureBuilder("classpath:features/cats.feature")
Check the system property / env variable feeding the path has a value before building
Use karate.options or defaults so the path is never built from empty input

Example fix

// before
String path = System.getProperty("feature", "");
KarateFeatureBuilder b = new KarateFeatureBuilder(path);
// after
String path = System.getProperty("feature", "classpath:features/cats.feature");
if (path == null || path.isEmpty()) throw new IllegalArgumentException("feature path not configured");
KarateFeatureBuilder b = new KarateFeatureBuilder(path);

Defensive patterns

Strategy: validation

Validate before calling

String path = System.getProperty("feature", "");
if (path == null || path.isEmpty()) { throw new IllegalArgumentException("feature path not configured"); }

Try / catch

try {
  KarateFeatureBuilder b = new KarateFeatureBuilder(path);
} catch (IllegalArgumentException e) {
  throw new IllegalStateException("Simulation misconfigured: " + e.getMessage(), e);
}

Prevention

Never build the path from an unset system property without a default
Validate simulation config at startup, before registering scenarios
Use classpath: prefixed paths consistently

When it happens

Trigger: new KarateFeatureBuilder(null) or new KarateFeatureBuilder("") — typically because the path comes from an empty system property, env variable, or config constant.

Common situations: Reading the feature path from a system property that was never set; refactoring simulations and leaving a placeholder empty string; generating the path programmatically and getting an empty result.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at karate-gatling/src/main/java/io/karatelabs/gatling/KarateFeatureBuilder.java:72

 * on the Gatling scenario rather than passing multiple paths here.
 */
public final class KarateFeatureBuilder implements ActionBuilder {

    private final String featurePath;
    private final List<String> tags = new ArrayList<>();
    private boolean silent = false;
    private KarateProtocol protocol;

    /**
     * Create a builder for the given feature path with optional tag selectors.
     *
     * @param path feature file path (e.g., "classpath:features/cats.feature")
     * @param tags tag selector expressions (e.g., "@smoke", "~@slow") — varargs;
     *             multiple values are AND-ed together, commas within a value are OR
     */
    public KarateFeatureBuilder(String path, String... tags) {
        if (path == null || path.isEmpty()) {
            throw new IllegalArgumentException("feature path is required");
        }
        this.featurePath = path;
        if (tags != null) {
            Collections.addAll(this.tags, tags);
        }
    }

    /**
     * Add tag filter expressions. Equivalent to passing tags to the constructor;
     * additional calls append to the existing tag list (all AND-ed together).
     *
     * @param tagExpressions tag expressions like "@smoke", "~@slow"
     * @return this builder
     */
    public KarateFeatureBuilder tags(String... tagExpressions) {
        if (tagExpressions != null) {
            Collections.addAll(tags, tagExpressions);
        }

View on GitHub (pinned to a22eb90246)