{"record":{"id":"1a265be541f538eb","repo":"oracle/graal","slug":"path-component-is-undefined","errorCode":null,"errorMessage":"Path component is undefined","messagePattern":"Path component is undefined","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"espresso/src/com.oracle.truffle.espresso.io/src/sun/nio/fs/TruffleFileSystemProvider.java","lineNumber":88,"sourceCode":"    TruffleFileSystem theFileSystem() {\n        return theFileSystem;\n    }\n\n    @Override\n    public String getScheme() {\n        return SCHEME;\n    }\n\n    private void checkUri(URI uri) {\n        if (!uri.getScheme().equalsIgnoreCase(getScheme())) {\n            throw new IllegalArgumentException(\"URI does not match this provider\");\n        }\n        if (uri.getRawAuthority() != null) {\n            throw new IllegalArgumentException(\"Authority component present\");\n        }\n        String path = uri.getPath();\n        if (path == null) {\n            throw new IllegalArgumentException(\"Path component is undefined\");\n        }\n        if (!path.equals(\"/\")) {\n            throw new IllegalArgumentException(\"Path component should be '/'\");\n        }\n        if (uri.getRawQuery() != null) {\n            throw new IllegalArgumentException(\"Query component present\");\n        }\n        if (uri.getRawFragment() != null) {\n            throw new IllegalArgumentException(\"Fragment component present\");\n        }\n    }\n\n    @Override\n    public FileSystem newFileSystem(URI uri, Map<String, ?> env) throws IOException {\n        checkUri(uri);\n        throw new FileSystemAlreadyExistsException();\n    }\n","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/oracle/graal/blob/a66e9ccd1d7bf2552883939aa0788dfd0e294aab/espresso/src/com.oracle.truffle.espresso.io/src/sun/nio/fs/TruffleFileSystemProvider.java#L70-L106","documentation":"Thrown by TruffleFileSystemProvider.checkUri when a URI passed to newFileSystem/getFileSystem/getPath has no path component (URI.getPath() returns null). The Truffle file system provider backs a single root-only file system, so every URI must carry an explicit, defined path. java.net.URI returns a null path for opaque URIs such as 'truffle:foo' where the scheme-specific part is not parsed as a path.","triggerScenarios":"Calling FileSystems.newFileSystem(uri, env) or provider.getFileSystem(uri) with an opaque URI like URI.create(\"truffle:something\") instead of a hierarchical one like URI.create(\"truffle:/\").","commonSituations":"Building the provider URI from string concatenation (scheme + \":\" + name) instead of scheme + \":/\", or copying a jar-filesystem URI pattern (jar:file:/...!) which has a completely different shape, when wiring Espresso/Truffle guest I/O.","solutions":["Pass a hierarchical URI with an explicit root path: URI.create(\"truffle:/\")","If constructing the URI from parts, always append '/' after the scheme (scheme + \":/\")","Verify uri.getPath() is non-null before calling newFileSystem/getFileSystem"],"exampleFix":"// before\nURI uri = URI.create(\"truffle:myfs\");\nFileSystem fs = FileSystems.newFileSystem(uri, Map.of());\n\n// after\nURI uri = URI.create(\"truffle:/\");\nFileSystem fs = FileSystems.getFileSystem(uri); // already-open singleton","handlingStrategy":"validation","validationCode":"URI uri = ...;\nif (uri.getPath() == null || !\"truffle\".equalsIgnoreCase(uri.getScheme())) {\n    throw new IllegalArgumentException(\"Truffle FS URI must be hierarchical, e.g. truffle:/\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Centralize construction of the Truffle file system URI in one constant: URI.create(\"truffle:/\")","Never build the URI from user input without validating scheme and path"],"tags":["espresso","nio","uri","filesystem","truffle"],"backgroundTag":null,"analyzedSha":"a66e9ccd1d7bf2552883939aa0788dfd0e294aab","analyzedAt":"2026-08-14T13:58:47.161Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}