What causes "Failed to scan extensions directory: ${extRoot}" in quarkusio/quarkus?

Verify the extensions directory path (extRoot) exists and is readable from the module where the mojo runs

quarkusio/quarkus · error · MojoExecutionException

Failed to scan extensions directory: ${extRoot}

Error message

Failed to scan extensions directory: ${extRoot}

What it means

AggregateSkillsMojo.discoverSkillFiles walks the extensions directory tree with a Files.walkFileTree visitor to collect skill files, aggregating extension documentation. If the walk throws an IOException, it is wrapped in a MojoExecutionException naming the extensions root directory that could not be scanned.

Source

Thrown at independent-projects/extension-maven-plugin/src/main/java/io/quarkus/maven/AggregateSkillsMojo.java:132

                            entries.add(new SkillEntry(file, runtimeYaml));
                        } else {
                            getLog().debug("No runtime quarkus-extension.yaml found for: " + file);
                        }
                    }
                    return FileVisitResult.CONTINUE;
                }

                @Override
                public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs) {
                    // Skip target directories for performance
                    if (dir.getFileName().toString().equals("target")) {
                        return FileVisitResult.SKIP_SUBTREE;
                    }
                    return FileVisitResult.CONTINUE;
                }
            });
        } catch (IOException e) {
            throw new MojoExecutionException("Failed to scan extensions directory: " + extRoot, e);
        }

        return entries;
    }

    /**
     * Checks that the file is under a {@code deployment/src/main/resources/META-INF/} path.
     */
    private boolean isDeploymentResourcePath(Path file) {
        // Walk up from quarkus-skill.md: META-INF / resources / main / src / deployment
        Path current = file.getParent(); // META-INF
        if (current == null)
            return false;
        current = current.getParent(); // resources
        if (current == null || !current.getFileName().toString().equals("resources"))
            return false;
        current = current.getParent(); // main
        if (current == null || !current.getFileName().toString().equals("main"))

View on GitHub (pinned to e1c734241f)

Solutions

Verify the extensions directory path (extRoot) exists and is readable from the module where the mojo runs
Fix file system permissions (chmod/chown) or run the build as a user with read access
Check for broken symlinks or inaccessible subdirectories under the extensions root
Run with -X to see the wrapped IOException cause for the exact failing path

Defensive patterns

Strategy: validation

Validate before calling

File extRoot = new File(configuredExtensionsDir);
if (!extRoot.isDirectory() || !extRoot.canRead()) {
  throw new IllegalStateException("extensions directory missing/unreadable: " + extRoot.getAbsolutePath());
}

Try / catch

try {
  invoker.executeMaven("aggregate-skills");
} catch (MojoExecutionException e) {
  if (e.getCause() instanceof IOException) { verifyExtensionsDirectory(); }
  throw e;
}

Prevention

Verify the extensionsDirectory parameter resolves before running aggregate-skills
Run the mojo from the correct module/checkout root
Check permissions of the extensions tree in CI images
Avoid symlinks into network mounts for the extensions directory

When it happens

Trigger: Running the aggregate-skills goal when Files.walkFileTree on the configured extensions root throws IOException — e.g. the directory does not exist, permission is denied, or an I/O error occurs mid-traversal.

Common situations: Wrong/quarkus.paths.exclusions or extensionsDirectory config pointing at a non-existent path; running the mojo outside a checkout with the expected extensions/ layout; restrictive file permissions in CI containers; broken symlinks causing traversal I/O errors.

Related errors

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