karatelabs/karate · error · DriverException

inputFile: file not found

Error message

inputFile: file not found: {ref} — 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 when the inputFile path reference cannot be resolved at all — neither through the feature's resource resolver nor as a plain host path. Karate distinguishes feature-relative paths, project-root paths (leading '/'), and host machine paths ('file:' prefix); the ref matched none.

Solutions

Fix the path: bare path relative to the feature, leading '/' for project root, 'file:' for a host machine path
Verify the file exists on disk at the expected location
Place the file under src/test/resources (or alongside the feature) so it is on the classpath
Pre-extract jar/remote resources to a real temp file and pass a 'file:' path

Example fix

// before
driver.inputFile("upload.txt", "#fileInput");
// after
driver.inputFile("file:" + "/absolute/path/upload.txt", "#fileInput");

Defensive patterns

Strategy: validation

Validate before calling

java.nio.file.Path p = java.nio.file.Paths.get("src/test/resources/upload.txt");
if (!java.nio.file.Files.exists(p)) {
    throw new IllegalStateException("input file missing: " + p.toAbsolutePath());
}
driver.inputFile("file:" + p.toAbsolutePath(), "#fileInput");

Try / catch

try {
    driver.inputFile(ref, "#fileInput");
} catch (DriverException e) {
    if (e.getMessage().startsWith("inputFile: file not found")) {
        throw new IllegalStateException("Fix ref: bare=feature-relative, '/'=project root, 'file:'=host path. " + e.getMessage(), e);
    } throw e;
}

Prevention

Keep upload fixtures next to the feature or under src/test/resources
Prefer feature-relative paths; use 'file:' only for host-absolute paths
Don't reference classpath/jar resources directly for inputFile
Verify files survive mvn clean

When it happens

Trigger: Calling driver.inputFile(ref, ...) with a typo'd or missing path; ref is a bare path relative to a feature directory where the file is not present; using an in-memory/jar resource where FeatureRuntime resolution fails and Resource.path(ref) also fails.

Common situations: Test resources not copied into the target/classpath location, running tests from a different working directory, refactoring moved the feature but not the fixture files, attempting to input files that exist only inside a jar or on a remote filesystem.

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/3a4389cd56cfd31a. Report an issue: GitHub.

Appendix: source

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

        List<String> files = new ArrayList<>(refs.length);
        for (String ref : refs) {
            files.add(resolveFilePath(ref));
        }
        return files;
    }

    private static String resolveFilePath(String ref) {
        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";
    }

View on GitHub (pinned to a22eb90246)