karatelabs/karate · error · DriverException

inputFile: not a local file

Error message

inputFile: not a local file: {ref} — the browser needs a real file on disk; extract it first, or point at it with 'file:'

What it means

Thrown by DriverApi.resolveFilePath when the reference resolves to something that is not a file on the local default filesystem. Browsers can only upload real host files, so Karate rejects refs that point into jars, in-memory filesystems, or other non-default FileSystem providers.

Solutions

  1. Extract the resource to a temp file on disk and pass its absolute path with the 'file:' prefix
  2. Copy the fixture into the test working directory instead of relying on the jar
  3. Configure the build to keep resources as loose files during tests

Example fix

// before
driver.inputFile("classpath:data/upload.pdf", "#fileInput");
// after
Path tmp = Files.copy(getClass().getResourceAsStream("/data/upload.pdf"),
        Files.createTempFile("upload", ".pdf"), StandardCopyOption.REPLACE_EXISTING);
driver.inputFile("file:" + tmp.toAbsolutePath(), "#fileInput");
Defensive patterns

Strategy: validation

Validate before calling

java.io.InputStream in = getClass().getResourceAsStream("/data/upload.pdf");
java.nio.file.Path tmp = java.nio.file.Files.createTempFile("upload", ".pdf");
java.nio.file.Files.copy(in, tmp, java.nio.file.StandardCopyOption.REPLACE_EXISTING);
driver.inputFile("file:" + tmp.toAbsolutePath(), "#fileInput");

Prevention

When it happens

Trigger: Calling driver.inputFile with a ref that resolves to a classpath/jar entry or a non-default (e.g. in-memory or cloud) filesystem path rather than an existing local disk file.

Common situations: Resources packaged inside the test jar, tests running under GraalVM/in-memory FS setups, pointing at remote/classpath URIs instead of extracted files.

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

Appendix: source

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

        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";
    }

    /**
     * Adapt a JS/Java callable argument to a {@code Supplier<Object>}.
     * <p>Karate treats inline JS lambdas as first-class Java callables — the

View on GitHub (pinned to a22eb90246)