quarkusio/quarkus · error · IOException

There were a problem while reading the resource dir '<name>'

Error message

There were a problem while reading the resource dir '<name>' on the classpath with url: '<url>'

What it means

getResourceFile attempted new File(url.toURI()) but the URL's syntax (or its form) is not convertible to a file URI — common with jar: URLs, URLs with spaces/odd characters, or non-file schemes. The original URL is preserved in the message for diagnosis.

Source

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

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());
        }
        throw new IllegalStateException("No compatible ResourceLoader have been found for file type: " + f.getName());
    }

    // This method is copied from io.quarkus.runtime.util.ClassPathUtils
    public static <R> R processAsPath(URL url, Function<Path, R> function) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Don't treat the resource as a File — consume it as a stream/Path instead (ResourceLoaders.processAsPath or loadResource)
2. URL-decode the URL and extract the jar entry path manually if a File is truly required
3. Move resources out of paths with spaces or use encoded URIs
4. Ensure the code runs in a plain file-based classloader context (not nested-jar/OSGi)

Example fix

// before
File f = ResourceLoaders.getResourceFile(url, name); // fails for jar: URLs
// after
ResourceLoaders.processAsPath(url, path -> consumer.consume(path));

if (!"file".equals(url.getProtocol())) {
    // not convertible to File — use stream/Path APIs instead
}

boolean isFileUrl(URL url) {
    return url != null && "file".equals(url.getProtocol());
}

try {
    return ResourceLoaders.getResourceFile(url, name);
} catch (IOException e) {
    if (e.getMessage().startsWith("There were a problem while reading")) {
        // fall back to stream-based access for jar:/nested URLs
        return ResourceLoaders.processAsPath(url, path -> consume(path));
    }
    throw e;
}

When it happens

Trigger: Calling getResourceFile(url, name) with a jar:/wsjar:/bundle: protocol URL, or a file: URL whose path contains characters that break URISyntax conversion.

Common situations: Running inside an app server/OSGi container where resources come from jars; resource paths with spaces (e.g. on Windows under 'Program Files'); nested-jar classloaders (Spring Boot fat jar).

Related errors

• Failed to create an instance of java.nio.file.Path from <url
• 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/5b07228e5a88cfae. Report an issue: GitHub.