{"record":{"id":"034cbc16fb8728f8","repo":"quarkusio/quarkus","slug":"failed-to-locate-name-on-the-classpath","errorCode":null,"errorMessage":"Failed to locate <name> on the classpath","messagePattern":"Failed to locate <name> on the classpath","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"independent-projects/tools/devtools-common/src/main/java/io/quarkus/platform/descriptor/loader/json/ClassPathResourceLoader.java","lineNumber":24,"sourceCode":"import java.net.URL;\n\npublic class ClassPathResourceLoader implements ResourceLoader {\n\n    private final ClassLoader cl;\n\n    public ClassPathResourceLoader() {\n        this(Thread.currentThread().getContextClassLoader());\n    }\n\n    public ClassPathResourceLoader(ClassLoader cl) {\n        this.cl = cl;\n    }\n\n    @Override\n    public <T> T loadResourceAsPath(String name, ResourcePathConsumer<T> consumer) throws IOException {\n        final URL url = cl.getResource(name);\n        if (url == null) {\n            throw new IOException(\"Failed to locate \" + name + \" on the classpath\");\n        }\n        return ResourceLoaders.processAsPath(url, is -> {\n            try {\n                return consumer.consume(is);\n            } catch (IOException e) {\n                throw new UncheckedIOException(e);\n            }\n        });\n    }\n\n    @Override\n    public <T> T loadResource(String name, ResourceInputStreamConsumer<T> consumer) throws IOException {\n        final InputStream stream = cl.getResourceAsStream(name);\n        if (stream == null) {\n            throw new IOException(\"Failed to locate \" + name + \" on the classpath\");\n        }\n        return consumer.consume(stream);\n    }","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/tools/devtools-common/src/main/java/io/quarkus/platform/descriptor/loader/json/ClassPathResourceLoader.java#L6-L42","documentation":"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.","triggerScenarios":"Calling loadResourceAsPath(name, ...) where cl.getResource(name) returns null — resource name typo, resource not packaged, or wrong classloader.","commonSituations":"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.","solutions":["Add the dependency that contains the resource (e.g. quarkus-platform-descriptor artifacts) to the classpath","Verify the exact resource path/name, including directories, is correct","Check build filters/shading config aren't excluding the resource","Dump classpath contents (jar tf) to confirm the resource is packaged"],"exampleFix":"// before\nloader.loadResourceAsPath(\"platform-descriptor.json\", consumer);\n// after: use the fully qualified resource path actually present in the jar\nloader.loadResourceAsPath(\"io/quarkus/platform/descriptor/json/quarkus-bom-quarkus-platform-descriptor-3.x.x.json\", consumer);","handlingStrategy":"try-catch","validationCode":"if (ClassLoader.getSystemResource(resourceName) == null\n        && Thread.currentThread().getContextClassLoader().getResource(resourceName) == null) {\n    throw new IllegalStateException(\"Resource not on classpath: \" + resourceName);\n}","typeGuard":"boolean classpathHas(ClassLoader cl, String name) {\n    return cl.getResource(name) != null;\n}","tryCatchPattern":"try {\n    return loader.loadResourceAsPath(name, consumer);\n} catch (IOException e) {\n    if (e.getMessage().equals(\"Failed to locate \" + name + \" on the classpath\")) {\n        throw new MissingDescriptorException(name, e);\n    }\n    throw e;\n}","preventionTips":["Add the descriptor/platform artifacts to your dependencies","Verify resource paths with `jar tf <jar> | grep <name>`","Check that shade/jar filters don't exclude resources","Prefer loading via stream (loadResource) when a Path is not strictly needed"],"tags":["classpath","io","resource-loading"],"backgroundTag":"classpath-resource-not-found","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}