oracle/graal · error · IllegalArgumentException

Path component is undefined

Error message

Path component is undefined

What it means

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.

Source

Thrown at espresso/src/com.oracle.truffle.espresso.io/src/sun/nio/fs/TruffleFileSystemProvider.java:88

    TruffleFileSystem theFileSystem() {
        return theFileSystem;
    }

    @Override
    public String getScheme() {
        return SCHEME;
    }

    private void checkUri(URI uri) {
        if (!uri.getScheme().equalsIgnoreCase(getScheme())) {
            throw new IllegalArgumentException("URI does not match this provider");
        }
        if (uri.getRawAuthority() != null) {
            throw new IllegalArgumentException("Authority component present");
        }
        String path = uri.getPath();
        if (path == null) {
            throw new IllegalArgumentException("Path component is undefined");
        }
        if (!path.equals("/")) {
            throw new IllegalArgumentException("Path component should be '/'");
        }
        if (uri.getRawQuery() != null) {
            throw new IllegalArgumentException("Query component present");
        }
        if (uri.getRawFragment() != null) {
            throw new IllegalArgumentException("Fragment component present");
        }
    }

    @Override
    public FileSystem newFileSystem(URI uri, Map<String, ?> env) throws IOException {
        checkUri(uri);
        throw new FileSystemAlreadyExistsException();
    }

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Pass a hierarchical URI with an explicit root path: URI.create("truffle:/")
2. If constructing the URI from parts, always append '/' after the scheme (scheme + ":/")
3. Verify uri.getPath() is non-null before calling newFileSystem/getFileSystem

Example fix

// before
URI uri = URI.create("truffle:myfs");
FileSystem fs = FileSystems.newFileSystem(uri, Map.of());

// after
URI uri = URI.create("truffle:/");
FileSystem fs = FileSystems.getFileSystem(uri); // already-open singleton

URI uri = ...;
if (uri.getPath() == null || !"truffle".equalsIgnoreCase(uri.getScheme())) {
    throw new IllegalArgumentException("Truffle FS URI must be hierarchical, e.g. truffle:/");
}

When it happens

Trigger: 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:/").

Common situations: 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.

Related errors

• Path component should be '/'
• Query component present
• Fragment component present
• Error setting up DirectIO
• URI does not match this provider

AI-assisted analysis of oracle/graal@a66e9ccd1d (2026-08-14). Data as JSON: /api/errors/1a265be541f538eb. Report an issue: GitHub.