oracle/graal · critical · IllegalStateException

No implementation of org.graalvm.home.HomeFinder could be fo

Error message

No implementation of org.graalvm.home.HomeFinder could be found

What it means

org.graalvm.home.HomeFinder.get() locates a HomeFinder implementation via ServiceLoader (module layer, then class loader, then context class loader fallbacks). If no service provider registers org.graalvm.home.HomeFinder — normally supplied by the GraalVM launcher/runtime via META-INF/services or a Provides module directive — it throws IllegalStateException. The exception means the code is running outside a real GraalVM installation or with a classpath missing the home provider.

Source

Thrown at sdk/src/org.graalvm.home/src/org/graalvm/home/HomeFinder.java:116

            return ImageSingletons.lookup(HomeFinder.class);
        } else {
            HomeFinder finder = instance;
            if (finder == null) {
                Class<?> lookupClass = HomeFinder.class;
                ModuleLayer moduleLayer = lookupClass.getModule().getLayer();
                Iterable<HomeFinder> services;
                if (moduleLayer != null) {
                    services = ServiceLoader.load(moduleLayer, HomeFinder.class);
                } else {
                    services = ServiceLoader.load(HomeFinder.class, lookupClass.getClassLoader());
                }
                Iterator<HomeFinder> iterator = services.iterator();
                if (!iterator.hasNext()) {
                    services = ServiceLoader.load(HomeFinder.class);
                    iterator = services.iterator();
                }
                if (!iterator.hasNext()) {
                    throw new IllegalStateException("No implementation of " + HomeFinder.class.getName() + " could be found");
                }
                finder = iterator.next();
                instance = finder;
            }
            return finder;
        }
    }

    private static volatile HomeFinder instance;
}

class HomeFinderFeature implements Feature {

    public String getURL() {
        return "https://github.com/oracle/graal/blob/master/sdk/src/org.graalvm.home/src/org/graalvm/home/HomeFinder.java";
    }

    public String getDescription() {

View on GitHub (pinned to a66e9ccd1d)

Solutions

Run the application on an actual GraalVM distribution (JAVA_HOME pointed at it) so the launcher-provided HomeFinder service is visible.
If embedding on a stock JVM, add the implementation artifact that registers the HomeFinder service to the runtime classpath/module path (check META-INF/services/org.graalvm.home.HomeFinder or module Provides directive).
For custom/module-layer launches, ensure ServiceLoader.load(moduleLayer, HomeFinder.class) can see the provider: add it to the configuration and resolution roots.
For tests, inject or mock the HomeFinder/Version instead of relying on discovery, or set the lookup to skip HomeFinder in non-Graal environments.

Example fix

// before
Version v = GraalVM.getVersion(); // plain JVM + sdk jar -> IllegalStateException

// after
// Run with GraalVM: JAVA_HOME=<graalvm-home> java -cp ... App
// or guard:
static Version safeVersion() {
    try { return GraalVM.getVersion(); }
    catch (IllegalStateException noHome) { return null; }
}

Defensive patterns

Strategy: try-catch

Validate before calling

static boolean isGraalHomeAvailable() {
    try {
        HomeFinder.get();
        return true;
    } catch (IllegalStateException e) {
        return false;
    }
}

Try / catch

try {
    Version v = GraalVM.getVersion();
} catch (IllegalStateException e) {
    // not running inside a GraalVM installation; degrade gracefully
    log.warn("GraalVM home not found; version-dependent features disabled");
}

Prevention

Run production binaries on an actual GraalVM distribution.
Verify the HomeFinder service entry (META-INF/services or module Provides) is on the runtime class/module path when embedding.
In tests, inject or mock version info instead of relying on ServiceLoader discovery.
Set JAVA_HOME to the GraalVM install in CI jobs that exercise GraalVM-specific code.

When it happens

Trigger: Calling GraalVM.getVersion() / HomeFinder.get() from a plain JDK application whose classpath includes org.graalvm.home (e.g. via the SDK jar) but not the implementation that registers the HomeFinder service; running unit tests in Maven/Gradle without the GraalVM runtime; modular applications whose module layer does not include the provider module; broken or partial GraalVM installations.

Common situations: Compiling against graal-sdk/org.graalvm.home jars downloaded from Maven Central and running on a stock HotSpot JVM; polyglot/embedded contexts launched with a custom ClassLoader that cannot see the service file; CI test jobs that never install a full GraalVM; module path setups missing a 'requires' on the provider module.

Related errors

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