karatelabs/karate · error · RuntimeException

Failed to materialize resource to

Error message

Failed to materialize resource to: {filename}

What it means

UrlResource.materialize writes the in-memory bytes to a target file (creating parent directories first); any failure in createDirectories or Files.write is wrapped as 'Failed to materialize resource to: {filename}'.

Solutions

1. Check the target directory exists and is writable by the process user (ls -ld, touch a test file)
2. Choose a writable location such as System.getProperty("java.io.tmpdir") or a project-local output dir
3. Inspect the cause of the RuntimeException — it names the exact filesystem error (AccessDeniedException, FileAlreadyExistsException, FileSystemException: No space left)
4. Ensure the filename itself is not an existing directory path

Example fix

// before
resource.materialize("/opt/app/bin/download.bin"); // may not be writable
// after
Path out = Paths.get(System.getProperty("java.io.tmpdir"), "karate-downloads");
Files.createDirectories(out);
resource.materialize(out.resolve("download.bin").toString());

Path target = Path.of(filename);
Path parent = target.toAbsolutePath().getParent();
if (parent != null) {
    Files.createDirectories(parent);            // fail fast with a clear error
    if (!Files.isWritable(parent)) {
        throw new AccessDeniedException(parent.toString());
    }
}

try {
    resource.materialize(filename);
} catch (RuntimeException e) {
    if (e.getCause() instanceof java.nio.file.FileSystemException fse) {
        throw new StorageException("cannot write " + filename + ": " + fse.getReason());
    }
    throw e;
}

When it happens

Trigger: Calling materialize(filename) on a UrlResource when the target directory cannot be created (permissions, path is actually a file) or the write fails (disk full, read-only filesystem, file locked by another process).

Common situations: Writing into a temp/output directory that does not exist and cannot be created due to sandbox permissions; downloading into a read-only packaged app directory; filename conflicts with an existing directory; disk quota exceeded in CI.

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

• embed(): failed to read part path
• Failed to backup existing dir
• Failed to clean:
• Failed to clean: karate-temp
• Failed to clean output directory:

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

Appendix: source

Thrown at karate-js/src/main/java/io/karatelabs/common/UrlResource.java:168

    /**
     * Materializes this URL 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 url != null ? url.toString() : getPrefixedPath();
    }

}

View on GitHub (pinned to a22eb90246)