{"record":{"id":"e0f86caa722eaa58","repo":"karatelabs/karate","slug":"inputfile-not-a-local-file-ref-the-browser-needs-a-real-file","errorCode":null,"errorMessage":"inputFile: not a local file: {ref} — the browser needs a real file on disk; extract it first, or point at it with 'file:'","messagePattern":"inputFile: not a local file: (.+?) — the browser needs a real file on disk; extract it first, or point at it with 'file:'","errorType":"exception","errorClass":"DriverException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/driver/DriverApi.java","lineNumber":177,"sourceCode":"        return files;\n    }\n\n    private static String resolveFilePath(String ref) {\n        if (ref.startsWith(Resource.FILE_COLON)) {\n            return Path.of(Resource.removePrefix(ref)).toAbsolutePath().normalize().toString();\n        }\n        ScenarioRuntime runtime = ScenarioRuntime.currentOrNull();\n        Resource resource;\n        try {\n            resource = runtime != null && runtime.getFeatureRuntime() != null\n                    ? runtime.getFeatureRuntime().resolve(ref)\n                    : Resource.path(ref);\n        } catch (Exception e) {\n            throw new DriverException(fileNotFoundMessage(ref, null), e);\n        }\n        Path path = resource.isFile() ? resource.getPath() : null;\n        if (path == null || path.getFileSystem() != FileSystems.getDefault()) {\n            throw new DriverException(\"inputFile: not a local file: \" + ref\n                    + \" — the browser needs a real file on disk; extract it first, or point at it with 'file:'\");\n        }\n        if (!resource.exists()) {\n            throw new DriverException(fileNotFoundMessage(ref, path));\n        }\n        return path.toAbsolutePath().normalize().toString();\n    }\n\n    private static String fileNotFoundMessage(String ref, Path resolved) {\n        return \"inputFile: file not found: \" + ref\n                + (resolved == null ? \"\" : \" (resolved to: \" + resolved.toAbsolutePath().normalize() + \")\")\n                + \" — a bare path is relative to the feature, a leading '/' anchors the project root,\"\n                + \" 'file:' is a host machine path\";\n    }\n\n    /**\n     * Adapt a JS/Java callable argument to a {@code Supplier<Object>}.\n     * <p>Karate treats inline JS lambdas as first-class Java callables — the","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/driver/DriverApi.java#L159-L195","documentation":"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.","triggerScenarios":"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.","commonSituations":"Resources packaged inside the test jar, tests running under GraalVM/in-memory FS setups, pointing at remote/classpath URIs instead of extracted files.","solutions":["Extract the resource to a temp file on disk and pass its absolute path with the 'file:' prefix","Copy the fixture into the test working directory instead of relying on the jar","Configure the build to keep resources as loose files during tests"],"exampleFix":"// before\ndriver.inputFile(\"classpath:data/upload.pdf\", \"#fileInput\");\n// after\nPath tmp = Files.copy(getClass().getResourceAsStream(\"/data/upload.pdf\"),\n        Files.createTempFile(\"upload\", \".pdf\"), StandardCopyOption.REPLACE_EXISTING);\ndriver.inputFile(\"file:\" + tmp.toAbsolutePath(), \"#fileInput\");","handlingStrategy":"validation","validationCode":"java.io.InputStream in = getClass().getResourceAsStream(\"/data/upload.pdf\");\njava.nio.file.Path tmp = java.nio.file.Files.createTempFile(\"upload\", \".pdf\");\njava.nio.file.Files.copy(in, tmp, java.nio.file.StandardCopyOption.REPLACE_EXISTING);\ndriver.inputFile(\"file:\" + tmp.toAbsolutePath(), \"#fileInput\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Extract any jar/classpath resource to a temp file before uploading","Only pass default-filesystem (real disk) paths to inputFile","Use the 'file:' prefix for extracted absolute paths"],"tags":["driver","file-upload","filesystem"],"backgroundTag":"file-not-found","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-16T19:17:19.609Z"}