karatelabs/karate · error · DriverException

inputFile: file not found

Error message

inputFile: file not found: {ref} (resolved to: {path}) — a bare path is relative to the feature, a leading '/' anchors the project root, 'file:' is a host machine path

What it means

Thrown by DriverApi.resolveFilePath (via fileNotFoundMessage) when the ref resolved to a candidate local path but the file does not exist. Unlike the unresolvable-path variant, this includes the resolved path so you can see exactly where Karate looked.

Solutions

  1. Check the '(resolved to: ...)' path in the message and verify the file exists there
  2. Fix the relative path or use a leading '/' to anchor at the project root
  3. Use the 'file:' prefix with an absolute host path as a last resort
  4. Ensure fixture files are in the classpath output (target/test-classes) at test time

Example fix

// before
driver.inputFile("fixtures/photo.png", "#upload"); // resolved to wrong dir
// after
driver.inputFile("/src/test/resources/fixtures/photo.png", "#upload");
// or absolute:
driver.inputFile("file:/home/dev/fixtures/photo.png", "#upload");
Defensive patterns

Strategy: validation

Validate before calling

String resolved = featureDir.resolve("fixtures/photo.png").normalize().toString();
if (!java.nio.file.Files.exists(java.nio.file.Paths.get(resolved))) {
    throw new IllegalStateException("fixture missing at: " + resolved);
}
driver.inputFile(resolved, "#upload");

Try / catch

try {
    driver.inputFile(ref, "#upload");
} catch (DriverException e) {
    if (e.getMessage().contains("(resolved to:")) {
        String lookedAt = e.getMessage().replaceAll(".*resolved to: ([^)]+)\).*", "$1");
        System.err.println("Karate looked at: " + lookedAt);
    } throw e;
}

Prevention

When it happens

Trigger: driver.inputFile(ref, ...) where ref resolved (feature-relative or project-root) to a concrete local path but no file exists there; wrong filename, wrong directory, file deleted by a clean build, or the leading '/' anchoring to an unexpected root.

Common situations: Files under src/test/resources not on the runtime classpath, features moved between directories, clean builds wiping generated fixtures, case-sensitivity mismatches on Linux.

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

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/DriverApi.java:181

        if (ref.startsWith(Resource.FILE_COLON)) {
            return Path.of(Resource.removePrefix(ref)).toAbsolutePath().normalize().toString();
        }
        ScenarioRuntime runtime = ScenarioRuntime.currentOrNull();
        Resource resource;
        try {
            resource = runtime != null && runtime.getFeatureRuntime() != null
                    ? runtime.getFeatureRuntime().resolve(ref)
                    : Resource.path(ref);
        } catch (Exception e) {
            throw new DriverException(fileNotFoundMessage(ref, null), e);
        }
        Path path = resource.isFile() ? resource.getPath() : null;
        if (path == null || path.getFileSystem() != FileSystems.getDefault()) {
            throw new DriverException("inputFile: not a local file: " + ref
                    + " — the browser needs a real file on disk; extract it first, or point at it with 'file:'");
        }
        if (!resource.exists()) {
            throw new DriverException(fileNotFoundMessage(ref, path));
        }
        return path.toAbsolutePath().normalize().toString();
    }

    private static String fileNotFoundMessage(String ref, Path resolved) {
        return "inputFile: file not found: " + ref
                + (resolved == null ? "" : " (resolved to: " + resolved.toAbsolutePath().normalize() + ")")
                + " — a bare path is relative to the feature, a leading '/' anchors the project root,"
                + " 'file:' is a host machine path";
    }

    /**
     * Adapt a JS/Java callable argument to a {@code Supplier<Object>}.
     * <p>Karate treats inline JS lambdas as first-class Java callables — the
     * same pattern that powers {@code karate.filter(list, x => ...)}.
     * This helper lets driver bindings route a callable argument to the
     * {@code Supplier}-taking overload of a method (polled locally in
     * karate-js) rather than coercing it to a string and shipping it off to

View on GitHub (pinned to a22eb90246)