{"record":{"id":"aeb5854e03f83205","repo":"neo4j/neo4j","slug":"storage-paths-cannot-be-converted-to-file-objects","errorCode":null,"errorMessage":"Storage paths cannot be converted to File objects","messagePattern":"Storage paths cannot be converted to File objects","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"community/cloud/src/main/java/org/neo4j/cloud/storage/StoragePath.java","lineNumber":382,"sourceCode":"    public int compareTo(Path other) {\n        final var storagePath = ensureStoragePath(other);\n        if (storagePath.storage != this.storage) {\n            throw new ClassCastException(\"compared storage paths must be from the same storage system\");\n        }\n\n        return toRealPath(NOFOLLOW_LINKS)\n                .toString()\n                .compareTo(storagePath.toRealPath(NOFOLLOW_LINKS).toString());\n    }\n\n    @Override\n    public Iterator<Path> iterator() {\n        return new StoragePathIterator(path.elements().iterator(), path.isAbsolute(), path.hasTrailingSeparator());\n    }\n\n    @Override\n    public File toFile() {\n        throw new UnsupportedOperationException(\"Storage paths cannot be converted to File objects\");\n    }\n\n    @Override\n    public WatchKey register(WatchService watcher, Kind<?>[] events, Modifier... modifiers) {\n        throw new UnsupportedOperationException(\"register\");\n    }\n\n    @Override\n    public WatchKey register(WatchService watcher, Kind<?>... events) {\n        throw new UnsupportedOperationException(\"register\");\n    }\n\n    @Override\n    public String toString() {\n        return path.toString();\n    }\n\n    @Override","sourceCodeStart":364,"sourceCodeEnd":400,"githubUrl":"https://github.com/neo4j/neo4j/blob/f213380f812b820a1b312e2ea52cb3d8f1931ccc/community/cloud/src/main/java/org/neo4j/cloud/storage/StoragePath.java#L364-L400","documentation":"StoragePath.toFile() throws UnsupportedOperationException because the path denotes an object in remote cloud storage that has no representation as a java.io.File (which is inherently local). The class chooses to fail fast rather than return a meaningless File pointing at a non-existent local location.","triggerScenarios":"Calling toFile() on a StoragePath — directly or via APIs that convert Path to File (legacy config loaders, File-based tooling, libraries calling path.toFile().exists() and friends).","commonSituations":"Legacy code predating NIO that works with File objects being handed cloud paths; third-party libraries accepting File arguments; plugins copying local-file idioms; toString()-derived File construction in configs.","solutions":["Replace File-based logic with NIO Path APIs (Files.exists(path), Files.newInputStream(path)) which work through the provider","Branch on path type and use local handling only for non-StoragePath inputs","For metadata (name, parent), use getFileName()/getParent() instead of File's name/parent methods"],"exampleFix":"// before\nFile f = path.toFile(); // throws\nboolean exists = f.exists();\n\n// after\nboolean exists = Files.exists(path);\nInputStream in = Files.newInputStream(path);","handlingStrategy":"type-guard","validationCode":"boolean fileConvertible(Path p) {\n    return !(p instanceof org.neo4j.cloud.storage.StoragePath);\n}","typeGuard":"static boolean isLocalPath(Path p) {\n    return !(p instanceof org.neo4j.cloud.storage.StoragePath);\n}","tryCatchPattern":"catch (UnsupportedOperationException e) on toFile(): switch the code path to NIO (Files.*) APIs which dispatch through the provider.","preventionTips":["Use NIO Path APIs (Files.exists/newInputStream/readAttributes) instead of File in storage-facing code","Refactor File-based APIs to accept Path","Ban path.toFile() in code that receives abstraction-resolved paths (lint rule/review checklist)"],"tags":["path","java-io-file","cloud-storage","legacy"],"backgroundTag":null,"analyzedSha":"f213380f812b820a1b312e2ea52cb3d8f1931ccc","analyzedAt":"2026-08-14T15:32:33.859Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}