What causes "failed to read file: " in karatelabs/karate?

Verify the read path resolves to a readable regular file; check permissions with `ls -l`.

karatelabs/karate · error · RuntimeException

failed to read file:

Error message

failed to read file:

What it means

When building a `multipart file` part whose value comes from a `read:` path, Karate resolves the resource (classpath or filesystem) and reads its bytes. If reading the resolved resource's stream fails, it wraps the exception in this RuntimeException naming the read path.

Solutions

Verify the read path resolves to a readable regular file; check permissions with `ls -l`.
Ensure the file is on the classpath (or use an absolute/relative filesystem path) and included in the build artifact.
If the path may not exist, pre-check with Java's Files.exists / karate's file utilities before the multipart step.
Wrap scenario setup so a missing fixture fails fast with a clear message.

Example fix

// before
And multipart file upload = { read: 'classpath:missing.txt' }
// after (verify fixture exists first)
* def text = karate.read('classpath:data/file.txt')
And multipart file upload = { read: 'classpath:data/file.txt', filename: 'file.txt' }

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check the resource resolves and is readable
* def path = 'classpath:data/file.txt'
* def exists = karate.read(path) != null
* assert exists

Try / catch

try {
    // multipart file step
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("failed to read file:")) {
        karate.log('Check fixture path/permissions: ' + e.getCause());
    }
    throw e;
}

Prevention

Keep fixtures under src/test/resources so they land on the classpath.
Verify file permissions, especially in CI containers.
Pre-read files with karate.read to fail fast with clearer errors.
Pass in-memory bytes via `value` when the file was already loaded.

When it happens

Trigger: `multipart file x = { read: 'some/path' }` where the resource exists enough to resolve a stream but reading fails — e.g. unreadable file permissions, directory instead of file, I/O error, or broken classpath resource.

Common situations: File exists at build time but not packaged into the test classpath/jar; path points to a directory; permissions changed; file deleted between resolution and read in CI.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/StepExecutor.java:2445

        Map<String, Object> multipartMap = new HashMap<>();
        multipartMap.put("name", name);

        if (value instanceof Map) {
            Map<String, Object> fileMap = (Map<String, Object>) value;
            // Handle { read: 'path', filename: 'name', contentType: 'type' }
            Object readPath = fileMap.get("read");
            if (readPath != null) {
                Resource resource = resolveResource(readPath.toString());
                File file = getFileFromResource(resource);
                if (file != null) {
                    multipartMap.put("value", file);
                } else {
                    // For classpath or in-memory resources, read bytes
                    try (InputStream is = resource.getStream()) {
                        byte[] bytes = is.readAllBytes();
                        multipartMap.put("value", bytes);
                    } catch (Exception e) {
                        throw new RuntimeException("failed to read file: " + readPath, e);
                    }
                }
            } else if (fileMap.get("value") != null) {
                multipartMap.put("value", fileMap.get("value"));
            }
            // Copy other properties
            if (fileMap.get("filename") != null) {
                multipartMap.put("filename", fileMap.get("filename"));
            }
            if (fileMap.get("contentType") != null) {
                multipartMap.put("contentType", fileMap.get("contentType"));
            }
            if (fileMap.get("charset") != null) {
                multipartMap.put("charset", fileMap.get("charset"));
            }
            if (fileMap.get("transferEncoding") != null) {
                multipartMap.put("transferEncoding", fileMap.get("transferEncoding"));
            }

View on GitHub (pinned to a22eb90246)