oracle/graal · error · IllegalArgumentException

Path component should be '/'

Error message

Path component should be '/'

What it means

Thrown by TruffleFileSystemProvider.checkUri when the URI's path component is defined but is not exactly '/'. The provider models a single root-only file system, so the URI must identify the root and nothing else; any deeper or empty-but-non-root path is rejected. Paths below the root are created via getPath, never via the URI.

Source

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

    @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();
    }

    @Override
    public FileSystem getFileSystem(URI uri) {
        checkUri(uri);

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Use exactly URI.create("truffle:/") when addressing the file system
2. Obtain sub-paths with fs.getPath("data", "file.txt") after acquiring the FileSystem, not via the URI
3. Prefer FileSystems.getFileSystem(...) over newFileSystem since the root FS already exists (newFileSystem throws FileSystemAlreadyExistsException)

Example fix

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

// after
FileSystem fs = FileSystems.getFileSystem(URI.create("truffle:/"));
Path data = fs.getPath("data", "file.txt");

if (!"/".equals(uri.getPath())) {
    throw new IllegalArgumentException("Truffle FS URI path must be '/', got: " + uri.getPath());
}

When it happens

Trigger: Calling newFileSystem/getFileSystem/getPath with URIs such as URI.create("truffle:/data"), URI.create("truffle://host/") (authority also rejected), or URI.create("truffle:") which yields an empty path "".

Common situations: Assuming the Truffle provider works like jar/zip providers where the URI carries the archive path, or trying to select a subdirectory by embedding it in the filesystem URI.

Related errors

• Path component is undefined
• 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/62924b14c417a3c4. Report an issue: GitHub.