quarkusio/quarkus · error · UncheckedIOException

Failed to load extension description

Error message

Failed to load extension description 

What it means

Thrown by GradleApplicationModelBuilder.readDescriptor as an UncheckedIOException when loading a Quarkus extension descriptor Properties file (quarkus-extension.properties / quarkus-extension.yaml support path) from the filesystem fails with an IOException. The descriptor path is included in the message. This typically means the extension descriptor file exists at the expected META-INF location but cannot be opened or read.

Source

Thrown at devtools/gradle/gradle-model/src/main/java/io/quarkus/gradle/tooling/GradleApplicationModelBuilder.java:603

        if (providesCapabilities != null) {
            modelBuilder
                    .addExtensionCapabilities(
                            CapabilityContract.of(artifactBuilder.toGACTVString(), providesCapabilities, null));
        }
        return true;
    }

    private static Properties readDescriptor(final Path path) {
        final Properties rtProps;
        if (!Files.exists(path)) {
            // not a platform artifact
            return null;
        }
        rtProps = new Properties();
        try (BufferedReader reader = Files.newBufferedReader(path)) {
            rtProps.load(reader);
        } catch (IOException e) {
            throw new UncheckedIOException("Failed to load extension description " + path, e);
        }
        return rtProps;
    }

    private static void initProjectModule(Project project, WorkspaceModule.Mutable module, SourceSet sourceSet,
            String classifier) {
        if (sourceSet == null) {
            return;
        }

        final FileCollection allClassesDirs = sourceSet.getOutput().getClassesDirs();
        // some plugins do not add source directories to source sets and they may be missing from sourceSet.getAllJava()
        // see https://github.com/quarkusio/quarkus/issues/20755

        final List<SourceDir> sourceDirs = new ArrayList<>(1);
        project.getTasks().withType(AbstractCompile.class,
                t -> configureCompileTask(t.getSource(), t.getDestinationDirectory(), allClassesDirs, sourceDirs, t,
                        sourceSet));

View on GitHub (pinned to e1c734241f)

Solutions

1. Check and fix file permissions on the descriptor path reported in the message (readable by the build user).
2. Remove the containing artifact directory from the cache and rebuild so it is recreated cleanly.
3. Stop concurrent builds/processes touching the same cache directory, then retry.
4. If on a shared/NFS cache, move the local repository to local disk (e.g. -Dmaven.repo.local or Gradle cache dir settings).
5. Inspect the wrapped IOException cause for the precise OS-level reason.

Example fix

# before: Failed to load extension description /cache/io/quarkus/.../META-INF/quarkus-extension.properties
sudo chown -R $USER ~/.gradle/caches ~/.m2/repository
# after: rebuild succeeds with readable descriptors

// Check descriptor readability before building:
def p = file('/path/to/META-INF/quarkus-extension.properties')
assert p.exists() && p.canRead() : "Extension descriptor ${p} is missing or unreadable"

try {
    quarkusBuild()
} catch (UncheckedIOException e) {
    if (e.message?.startsWith('Failed to load extension description')) {
        logger.error('Unreadable extension descriptor: ' + e.message + ' / cause: ' + e.cause)
    } else throw e
}

When it happens

Trigger: processQuarkusDir/extProps resolves a descriptor path (inside an expanded directory artifact or extracted META-INF), the file exists (so the null-return guard passes), Files.newBufferedReader(path) succeeds but the subsequent read or the BufferedReader open races with deletion, hits permission denial, or the path is an unreadable directory entry.

Common situations: File permission issues on cached artifacts; the descriptor file being deleted/modified concurrently by another build process; filesystem errors (disk issues, NFS mounts); running builds as different users sharing a Gradle/Maven cache with mixed ownership.

Related errors

• Failed to load extension description + path
• Failed to process
• Failed to hash content of
• Failed to open path tree with root %s
• Failed to read %s

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