quarkusio/quarkus · error · IOException

Failed to locate resource <name> on the classpath

Error message

Failed to locate resource <name> on the classpath

What it means

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.

Source

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

import java.nio.file.Paths;
import java.util.Objects;
import java.util.function.Function;

import org.apache.commons.io.FilenameUtils;

import io.quarkus.fs.util.ZipUtils;

public final class ResourceLoaders {

    private static final String FILE = "file";
    private static final String JAR = "jar";

    private ResourceLoaders() {
    }

    public static File getResourceFile(final URL url, final String name) throws IOException {
        if (url == null) {
            throw new IOException("Failed to locate resource " + name + " on the classpath");
        }
        try {
            return new File(url.toURI());
        } catch (URISyntaxException | IllegalArgumentException e) {
            throw new IOException(
                    "There were a problem while reading the resource dir '" + name + "' on the classpath with url: '"
                            + url.toString() + "'");
        }
    }

    public static ResourceLoader resolveFileResourceLoader(File f) {
        Objects.requireNonNull(f, "f is required");
        if (f.isDirectory()) {
            return new DirectoryResourceLoader(f.toPath());
        }
        if (f.isFile() && FilenameUtils.isExtension(f.getName(), "jar", "zip")) {
            return new ZipResourceLoader(f.toPath());
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure the resource exists on the classpath before calling (check cl.getResource first)
2. Add the missing dependency containing the resource
3. Fix the resource name/path
4. Handle null defensively at the call site before invoking getResourceFile

Example fix

// before
URL url = cl.getResource(name); // may be null
File f = ResourceLoaders.getResourceFile(url, name); // throws
// after
URL url = cl.getResource(name);
if (url == null) {
    throw new SkipProcessing(); // or fallback path
}
File f = ResourceLoaders.getResourceFile(url, name);

URL url = cl.getResource(name);
if (url == null) {
    throw new IllegalStateException("Resource missing from classpath: " + name);
}
File f = ResourceLoaders.getResourceFile(url, name);

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

try {
    return ResourceLoaders.getResourceFile(url, name);
} catch (IOException e) {
    if (e.getMessage().startsWith("Failed to locate resource")) {
        throw new MissingDescriptorException(name, e);
    }
    throw e;
}

When it happens

Trigger: Calling getResourceFile(null, name) — typically after a cl.getResource(name) lookup the caller didn't null-check, often for a directory-style resource.

Common situations: Locating descriptor directories on the classpath that don't exist because the platform artifact isn't a dependency; resource filtered out of the jar.

Related errors

• Failed to locate <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/93627f90892cacee. Report an issue: GitHub.