karatelabs/karate · error · RuntimeException

Failed to materialize resource to

Error message

Failed to materialize resource to: {filename}

What it means

MemoryResource.materialize() writes the in-memory resource's bytes to a real file on disk (used when an API requires a path-backed resource, e.g. for HTML report output). Any failure creating parent directories or writing the bytes is wrapped in this RuntimeException, keeping the original exception as the cause.

Solutions

1. Check the exception cause for the underlying filesystem error (permission denied vs disk full vs invalid path)
2. Ensure the target directory exists and is writable by the process user
3. Free disk space or point output to a writable directory (e.g. mvn surefire reportDirectory config)
4. Verify the filename/path is valid for the platform (no illegal characters, not inside a file)

Example fix

// before (read-only dir)
resource.materialize("/usr/share/report.html")
// after (writable build dir)
resource.materialize("target/report.html")

// Java: pre-validate the target location is writable
Path target = Paths.get("target/report.html");
Path parent = target.toAbsolutePath().getParent();
if (parent == null || !Files.isDirectory(parent) || !Files.isWritable(parent)) {
    throw new IllegalStateException("cannot materialize into: " + parent);
}

try {
    Resource r = memResource.materialize("target/report.html");
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Failed to materialize resource to:")) {
        logger.error("materialize failed: {}", e.getCause());
    }
}

When it happens

Trigger: Writing to a read-only directory or a path without write permission; parent directory creation fails (permission denied, path exists as a file); disk full; the filename resolves to an invalid/illegal path on the OS; SecurityManager or sandbox blocks the write.

Common situations: Running tests in a read-only CI workspace; output dir owned by a different user; target path colliding with an existing regular file; running in a container with a read-only filesystem or full tmpfs.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• image.write: failed to write
• Failed to open stream for
• Failed to read text from
• Failed to read bytes from
• ext ' ': resource vanished after validation

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

Appendix: source

Thrown at karate-js/src/main/java/io/karatelabs/common/MemoryResource.java:227

    /**
     * Materializes this in-memory resource to disk at the specified filename.
     * The file is created within the root directory.
     *
     * @param filename the filename to save as
     * @return PathResource pointing to the saved file
     */
    public PathResource materialize(String filename) {
        try {
            Path target = root.resolve(filename);
            // Ensure parent directories exist
            if (target.getParent() != null) {
                Files.createDirectories(target.getParent());
            }
            Files.write(target, bytes());
            return new PathResource(target, root);
        } catch (Exception e) {
            throw new RuntimeException("Failed to materialize resource to: " + filename, e);
        }
    }

    @Override
    public InputStream getStream() {
        return new ByteArrayInputStream(bytes());
    }

    @Override
    public String toString() {
        return getPrefixedPath();
    }

}

View on GitHub (pinned to a22eb90246)