quarkusio/quarkus · error · IllegalStateException

No compatible ResourceLoader have been found for file type:

Error message

No compatible ResourceLoader have been found for file type: <fileName>

What it means

resolveFileResourceLoader inspects a File and returns a DirectoryResourceLoader for directories or a ZipResourceLoader for .jar/.zip files. Anything else (other extensions, symlinks to nothing, non-regular files) has no compatible loader, so it throws IllegalStateException naming the file.

Source

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

        }
        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) {
        if (JAR.equals(url.getProtocol())) {
            final String file = url.getFile();
            final int exclam = file.lastIndexOf('!');
            final Path jar;
            try {
                jar = toLocalPath(exclam >= 0 ? new URL(file.substring(0, exclam)) : url);
            } catch (MalformedURLException e) {
                throw new RuntimeException("Failed to create a URL for '" + file.substring(0, exclam) + "'", e);
            }
            try (FileSystem jarFs = ZipUtils.newFileSystem(jar)) {
                Path localPath = jarFs.getPath("/");
                if (exclam >= 0) {
                    localPath = localPath.resolve(file.substring(exclam + 1));
                }

View on GitHub (pinned to e1c734241f)

Solutions

  1. Rename the file to have a .jar or .zip extension if it is actually one
  2. Ensure the file is a real directory if you intended a directory loader
  3. Re-download/rebuild the artifact — the file may be corrupt or partial
  4. Extend the extension check in resolveFileResourceLoader if you control the code and need more formats

Example fix

// before
ResourceLoaders.resolveFileResourceLoader(new File("repo/descriptor.tar.gz")); // throws
// after: use a supported artifact
ResourceLoaders.resolveFileResourceLoader(new File("repo/descriptor-3.2.0.jar"));
Defensive patterns

Strategy: validation

Validate before calling

File f = ...;
if (!(f.isDirectory() || FilenameUtils.isExtension(f.getName(), "jar", "zip"))) {
    throw new IllegalArgumentException("Unsupported resource file: " + f);
}

Type guard

boolean hasCompatibleLoader(File f) {
    return f != null && (f.isDirectory() || FilenameUtils.isExtension(f.getName(), "jar", "zip"));
}

Try / catch

try {
    loader = ResourceLoaders.resolveFileResourceLoader(f);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("No compatible ResourceLoader")) {
        throw new ConfigurationException("Descriptor source must be a directory, .jar or .zip: " + f, e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling resolveFileResourceLoader(f) where f is an existing regular file whose extension is not jar/zip (e.g. .tar.gz, no extension), or a special file that is neither directory nor jar/zip.

Common situations: Pointing platform-descriptor resolution at an unpacked-but-misnamed artifact, a .war/.rar, or a partially downloaded file; local repository file renamed without its .jar extension.

Related errors

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