karatelabs/karate · error · IllegalArgumentException

boot.classpath: dir is null — pass a project-relative…

Error message

boot.classpath: dir is null — pass a project-relative directory such as 'src/test/resources', or '' for the project root

What it means

BootBinding.classpath(dir) configures the project-relative directory that boot.read() uses to resolve classpath: references. Passing null gives no information about where to root the classpath mapping, so an IllegalArgumentException is thrown immediately with guidance on acceptable values ('' meaning project root is valid).

Solutions

Pass an explicit project-relative directory string, e.g. boot.classpath('src/test/resources').
Use boot.classpath('') if you want the project root itself.
Check any interpolated variable feeding the call for null/undefined values at boot time.

Example fix

// before
boot.classpath(myDir); // myDir may be null
// after
boot.classpath(myDir == null ? 'src/test/resources' : myDir);

Defensive patterns

Strategy: validation

Validate before calling

// before calling boot.classpath(dir)
if (dir == null) dir = ""; // default to project root, or throw your own clear error

Try / catch

try {
    boot.classpath(dir);
} catch (IllegalArgumentException e) {
    // log misconfigured boot script and fail fast with your own message
}

Prevention

Never pass interpolated values that can be null; default to '' for project root.
Keep boot config free of env-dependent directory arguments, or provide explicit defaults.
Prefer literal directory strings in boot configuration.

When it happens

Trigger: Calling boot.classpath(null) — or calling it with an expression that evaluates to null at boot time (e.g. an unset config variable).

Common situations: A boot configuration script interpolates a directory from an environment variable or property that is unset, producing null; copy-pasted boot config where the argument was accidentally deleted.

Related errors

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/BootBinding.java:150

    }

    /**
     * {@code boot.classpath('src/test/resources')} — <b>declare the resource root</b>: the directory
     * a {@code classpath:} reference retries against when the classloader misses, and (in a Java
     * Runner-lane run that did not set an explicit working dir) the directory the working dir
     * re-anchors to. One committed line makes a Maven/Gradle project resolve its references
     * identically under a JVM run — where the classloader hits and this mapping stays inert — and
     * under a bare-folder serve run, where the fallback carries {@code classpath:} refs to the
     * declared dir.
     *
     * <p>The argument is a <b>root-relative reference</b>, so {@code file:} / {@code classpath:} /
     * {@code this:} and Windows drive-letter absolutes are rejected. {@code ''} is valid and means
     * the root itself (the "unify only, map nothing" spelling) — which is also what an undeclared
     * project gets, so a bare-folder project never needs this call. Last call wins.</p>
     */
    public void classpath(String dir) {
        if (dir == null) {
            throw new IllegalArgumentException("boot.classpath: dir is null — pass a project-relative "
                    + "directory such as 'src/test/resources', or '' for the project root");
        }
        if (dir.startsWith(Resource.FILE_COLON) || dir.startsWith(Resource.CLASSPATH_COLON)
                || dir.startsWith(Resource.THIS_COLON)
                || (!dir.startsWith("/") && java.nio.file.Path.of(dir).isAbsolute())) {
            throw new IllegalArgumentException("boot.classpath('" + dir + "'): expected a directory "
                    + "RELATIVE to the project root (e.g. 'src/test/resources'), not an absolute or "
                    + "prefixed reference");
        }
        this.classpathDir = Resource.stripLeadingSlashes(dir);
    }

    /**
     * The directory declared by {@link #classpath(String)}, root-relative and de-slashed, or
     * {@code null} when the project declared nothing (then the fallback dir IS the root).
     */
    public String getClasspathDir() {
        return classpathDir;

View on GitHub (pinned to a22eb90246)