{"record":{"id":"e3d6111f387fdec0","repo":"karatelabs/karate","slug":"failed-to-materialize-resource-to-filename-urlresource","errorCode":null,"errorMessage":"Failed to materialize resource to: {filename}","messagePattern":"Failed to materialize resource to: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-js/src/main/java/io/karatelabs/common/UrlResource.java","lineNumber":168,"sourceCode":"\n    /**\n     * Materializes this URL resource to disk at the specified filename.\n     * The file is created within the root directory.\n     *\n     * @param filename the filename to save as\n     * @return PathResource pointing to the saved file\n     */\n    public PathResource materialize(String filename) {\n        try {\n            Path target = root.resolve(filename);\n            // Ensure parent directories exist\n            if (target.getParent() != null) {\n                Files.createDirectories(target.getParent());\n            }\n            Files.write(target, bytes);\n            return new PathResource(target, root);\n        } catch (Exception e) {\n            throw new RuntimeException(\"Failed to materialize resource to: \" + filename, e);\n        }\n    }\n\n    @Override\n    public InputStream getStream() {\n        return new ByteArrayInputStream(bytes);\n    }\n\n    @Override\n    public String toString() {\n        return url != null ? url.toString() : getPrefixedPath();\n    }\n\n}\n","sourceCodeStart":150,"sourceCodeEnd":183,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-js/src/main/java/io/karatelabs/common/UrlResource.java#L150-L183","documentation":"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}'.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check the target directory exists and is writable by the process user (ls -ld, touch a test file)","Choose a writable location such as System.getProperty(\"java.io.tmpdir\") or a project-local output dir","Inspect the cause of the RuntimeException — it names the exact filesystem error (AccessDeniedException, FileAlreadyExistsException, FileSystemException: No space left)","Ensure the filename itself is not an existing directory path"],"exampleFix":"// before\nresource.materialize(\"/opt/app/bin/download.bin\"); // may not be writable\n// after\nPath out = Paths.get(System.getProperty(\"java.io.tmpdir\"), \"karate-downloads\");\nFiles.createDirectories(out);\nresource.materialize(out.resolve(\"download.bin\").toString());","handlingStrategy":"try-catch","validationCode":"Path target = Path.of(filename);\nPath parent = target.toAbsolutePath().getParent();\nif (parent != null) {\n    Files.createDirectories(parent);            // fail fast with a clear error\n    if (!Files.isWritable(parent)) {\n        throw new AccessDeniedException(parent.toString());\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    resource.materialize(filename);\n} catch (RuntimeException e) {\n    if (e.getCause() instanceof java.nio.file.FileSystemException fse) {\n        throw new StorageException(\"cannot write \" + filename + \": \" + fse.getReason());\n    }\n    throw e;\n}","preventionTips":["Materialize into java.io.tmpdir or a dedicated writable output directory","Check disk free space before large downloads","Never materialize over a path that is an existing directory","In CI, grant write permissions on the workspace/output volume"],"tags":["file-io","filesystem","write"],"backgroundTag":"file-write-failed","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}