oracle/graal · error · IllegalArgumentException

URI does not match this provider

Error message

URI does not match this provider

What it means

TruffleFileSystemProvider.checkUri validates URIs passed to newFileSystem/getFileSystem: the scheme must equal the provider's scheme (case-insensitive). A mismatch throws IllegalArgumentException('URI does not match this provider'), mirroring java.nio.file.FileSystemProvider contract checks.

Source

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

    static final String SEPARATOR = getSeparator0();

    TruffleFileSystemProvider() {
        this.theFileSystem = new TruffleFileSystem(this);
    }

    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");
        }
    }

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Check provider.getScheme().equalsIgnoreCase(uri.getScheme()) before calling the provider.
2. Use FileSystems.newFileSystem(uri, env), which routes by scheme automatically.
3. Construct the URI with the correct provider scheme constant.

Example fix

// before
TruffleFileSystemProvider p = ...;
p.newFileSystem(URI.create("file:///data"), Map.of()); // wrong scheme -> throws

// after
if (p.getScheme().equalsIgnoreCase(uri.getScheme())) {
    p.newFileSystem(uri, Map.of());
}

if (provider.getScheme().equalsIgnoreCase(uri.getScheme())) {
    provider.newFileSystem(uri, env);
} else {
    // route to the correct provider or use FileSystems.newFileSystem(uri, env)
}

try {
    provider.newFileSystem(uri, env);
} catch (IllegalArgumentException e) {
    if (e.getMessage().equals("URI does not match this provider")) { /* wrong provider; skip */ }
}

When it happens

Trigger: Calling FileSystems.newFileSystem(uri, env) or provider.newFileSystem(uri, env) with a URI whose scheme is not the Truffle scheme (e.g. 'jar:', 'file:', custom scheme) while routing to this provider, or manually invoking the provider from ServiceLoader iteration.

Common situations: Code iterating installed providers and calling each with an arbitrary URI; copy-pasted URI construction with the wrong scheme; URI scheme case differences are tolerated but wrong schemes are not.

Related errors

• Authority component present
• Path component is undefined
• Path component should be '/'
• Query component present
• Fragment component present

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