quarkusio/quarkus · error · IOException

Failed to locate <name> on the classpath

Error message

Failed to locate <name> on the classpath

What it means

ClassPathResourceLoader.loadResourceAsPath resolves a named resource via the classloader and throws IOException if the resource URL is null. It means the requested descriptor/resource (e.g. a platform descriptor JSON) is not present on the classpath of the running application.

Source

Thrown at independent-projects/tools/devtools-common/src/main/java/io/quarkus/platform/descriptor/loader/json/ClassPathResourceLoader.java:24

import java.net.URL;

public class ClassPathResourceLoader implements ResourceLoader {

    private final ClassLoader cl;

    public ClassPathResourceLoader() {
        this(Thread.currentThread().getContextClassLoader());
    }

    public ClassPathResourceLoader(ClassLoader cl) {
        this.cl = cl;
    }

    @Override
    public <T> T loadResourceAsPath(String name, ResourcePathConsumer<T> consumer) throws IOException {
        final URL url = cl.getResource(name);
        if (url == null) {
            throw new IOException("Failed to locate " + name + " on the classpath");
        }
        return ResourceLoaders.processAsPath(url, is -> {
            try {
                return consumer.consume(is);
            } catch (IOException e) {
                throw new UncheckedIOException(e);
            }
        });
    }

    @Override
    public <T> T loadResource(String name, ResourceInputStreamConsumer<T> consumer) throws IOException {
        final InputStream stream = cl.getResourceAsStream(name);
        if (stream == null) {
            throw new IOException("Failed to locate " + name + " on the classpath");
        }
        return consumer.consume(stream);
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the dependency that contains the resource (e.g. quarkus-platform-descriptor artifacts) to the classpath
2. Verify the exact resource path/name, including directories, is correct
3. Check build filters/shading config aren't excluding the resource
4. Dump classpath contents (jar tf) to confirm the resource is packaged

Example fix

// before
loader.loadResourceAsPath("platform-descriptor.json", consumer);
// after: use the fully qualified resource path actually present in the jar
loader.loadResourceAsPath("io/quarkus/platform/descriptor/json/quarkus-bom-quarkus-platform-descriptor-3.x.x.json", consumer);

if (ClassLoader.getSystemResource(resourceName) == null
        && Thread.currentThread().getContextClassLoader().getResource(resourceName) == null) {
    throw new IllegalStateException("Resource not on classpath: " + resourceName);
}

boolean classpathHas(ClassLoader cl, String name) {
    return cl.getResource(name) != null;
}

try {
    return loader.loadResourceAsPath(name, consumer);
} catch (IOException e) {
    if (e.getMessage().equals("Failed to locate " + name + " on the classpath")) {
        throw new MissingDescriptorException(name, e);
    }
    throw e;
}

When it happens

Trigger: Calling loadResourceAsPath(name, ...) where cl.getResource(name) returns null — resource name typo, resource not packaged, or wrong classloader.

Common situations: Requesting a Quarkus platform descriptor like io/quarkus/platform/... json that isn't a dependency; resource excluded by build filters; running in a shaded/native context where the resource wasn't included.

Related errors

• Failed to locate resource <name> on the classpath
• Failed to read %s
• Failed to read resources from classpath
• Could not read class path resources having path '${resourceP
• Failed to load + pomPropsPath + from the classpath

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/034cbc16fb8728f8. Report an issue: GitHub.