{"record":{"id":"93627f90892cacee","repo":"quarkusio/quarkus","slug":"failed-to-locate-resource-name-on-the-classpath","errorCode":null,"errorMessage":"Failed to locate resource <name> on the classpath","messagePattern":"Failed to locate resource <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/ResourceLoaders.java","lineNumber":29,"sourceCode":"import java.nio.file.Paths;\nimport java.util.Objects;\nimport java.util.function.Function;\n\nimport org.apache.commons.io.FilenameUtils;\n\nimport io.quarkus.fs.util.ZipUtils;\n\npublic final class ResourceLoaders {\n\n    private static final String FILE = \"file\";\n    private static final String JAR = \"jar\";\n\n    private ResourceLoaders() {\n    }\n\n    public static File getResourceFile(final URL url, final String name) throws IOException {\n        if (url == null) {\n            throw new IOException(\"Failed to locate resource \" + name + \" on the classpath\");\n        }\n        try {\n            return new File(url.toURI());\n        } catch (URISyntaxException | IllegalArgumentException e) {\n            throw new IOException(\n                    \"There were a problem while reading the resource dir '\" + name + \"' on the classpath with url: '\"\n                            + url.toString() + \"'\");\n        }\n    }\n\n    public static ResourceLoader resolveFileResourceLoader(File f) {\n        Objects.requireNonNull(f, \"f is required\");\n        if (f.isDirectory()) {\n            return new DirectoryResourceLoader(f.toPath());\n        }\n        if (f.isFile() && FilenameUtils.isExtension(f.getName(), \"jar\", \"zip\")) {\n            return new ZipResourceLoader(f.toPath());\n        }","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/tools/devtools-common/src/main/java/io/quarkus/platform/descriptor/loader/json/ResourceLoaders.java#L11-L47","documentation":"ResourceLoaders.getResourceFile converts a resource URL to a File and throws IOException when the URL itself is null, i.e. the resource was never found on the classpath. Unlike the other loaders it operates on an already-resolved URL, so this is the 'caller passed null' case.","triggerScenarios":"Calling getResourceFile(null, name) — typically after a cl.getResource(name) lookup the caller didn't null-check, often for a directory-style resource.","commonSituations":"Locating descriptor directories on the classpath that don't exist because the platform artifact isn't a dependency; resource filtered out of the jar.","solutions":["Ensure the resource exists on the classpath before calling (check cl.getResource first)","Add the missing dependency containing the resource","Fix the resource name/path","Handle null defensively at the call site before invoking getResourceFile"],"exampleFix":"// before\nURL url = cl.getResource(name); // may be null\nFile f = ResourceLoaders.getResourceFile(url, name); // throws\n// after\nURL url = cl.getResource(name);\nif (url == null) {\n    throw new SkipProcessing(); // or fallback path\n}\nFile f = ResourceLoaders.getResourceFile(url, name);","handlingStrategy":"type-guard","validationCode":"URL url = cl.getResource(name);\nif (url == null) {\n    throw new IllegalStateException(\"Resource missing from classpath: \" + name);\n}\nFile f = ResourceLoaders.getResourceFile(url, name);","typeGuard":"boolean isResolvable(ClassLoader cl, String name) {\n    return cl.getResource(name) != null;\n}","tryCatchPattern":"try {\n    return ResourceLoaders.getResourceFile(url, name);\n} catch (IOException e) {\n    if (e.getMessage().startsWith(\"Failed to locate resource\")) {\n        throw new MissingDescriptorException(name, e);\n    }\n    throw e;\n}","preventionTips":["Always null-check cl.getResource before calling getResourceFile","Ensure the owning artifact is a declared dependency","Verify resource names after dependency upgrades"],"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-14T00:17:10.932Z"}