karatelabs/karate · error · RuntimeException

Failed to open stream for:

Error message

Failed to open stream for: 

What it means

After resolving the path against the current resource context, karate.readAsStream() calls resource.getStream() to open the file. If opening the stream fails for any reason (missing file, unreadable path, I/O error), Karate wraps the original exception in a RuntimeException carrying "Failed to open stream for: <path>" with the underlying cause attached.

Solutions

1. Check the cause chained in the exception (getCause()) to see whether it is NoSuchFileException, AccessDeniedException, etc.
2. Verify the file exists at the resolved location: use karate.read(path) first (its 'file not found' message is clearer) or list the resource directory
3. Fix the path relative to the current feature — use 'classpath:' prefix for test resources: karate.readAsStream('classpath:data/large.csv')
4. Ensure the file is included in the build (test resources copy / jar packaging) and is a regular file, not a directory
5. Fix filesystem permissions on the file in CI environments

Example fix

// before
var stream = karate.readAsStream('data/large.csv'); // fails: file not on resolved path

// after
var stream = karate.readAsStream('classpath:data/large.csv'); // correct location verified to exist

// Resolve and existence-check the path the same way Karate does before streaming:
// use karate.read(path) as a cheap probe, or verify via build config that the resource exists:
// ls src/test/resources/data/large.csv   (must match the relative path passed)

try {
  var stream = karate.readAsStream(path);
} catch (e) {
  if (('' + e).indexOf('Failed to open stream for:') !== -1) {
    karate.log('cannot open: ' + path + ' cause: ' + e.javaException.getCause());
    fail('resource missing or unreadable: ' + path);
  }
  throw e;
}

When it happens

Trigger: Calling karate.readAsStream(path) where the resolved Resource cannot be opened: the file does not exist relative to the feature/classpath root, the path resolves to a directory, file permissions deny reading, or the stream is already consumed/closed.

Common situations: Typo in the file name or wrong relative path (file lives in a different module or resource dir); file not copied into test resources; running from a jar where the resource path differs; reading a directory instead of a file; OS-level permission restrictions in CI.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

• readAsStream() needs at least one argument
• embed(): failed to read part path
• failed to read file:
• input must not be null
• input string must not be empty or blank

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/KarateJs.java:1087

        }
        return prevResponse;
    }

    /**
     * karate.readAsStream(path) - Read file as InputStream.
     * Useful for streaming large files without loading into memory.
     */
    private JavaInvokable readAsStream() {
        return args -> {
            if (args.length == 0) {
                throw new RuntimeException("readAsStream() needs at least one argument");
            }
            String path = args[0] + "";
            Resource resource = getCurrentResource().resolve(path);
            try {
                return resource.getStream();
            } catch (Exception e) {
                throw new RuntimeException("Failed to open stream for: " + path, e);
            }
        };
    }

    /**
     * karate.render(template) - Render HTML template (similar to doc).
     * Returns the rendered HTML string without sending to doc consumer.
     */
    @SuppressWarnings("unchecked")
    private JavaInvokable render() {
        return args -> {
            if (args.length == 0) {
                throw new RuntimeException("render() needs at least one argument");
            }
            String readPath;
            Map<String, Object> vars = null;
            if (args[0] instanceof Map) {
                Map<String, Object> map = (Map<String, Object>) args[0];

View on GitHub (pinned to a22eb90246)