What causes "Failed to walk directory " in quarkusio/quarkus?

Check the directory exists and is readable (ls/permissions) and recreate it (e.g. re-run build)

quarkusio/quarkus · error · java.io.UncheckedIOException

Failed to walk directory

Error message

Failed to walk directory

What it means

walkInformationForPath wraps IOExceptions from Files.walkFileTree (directory traversal) into an UncheckedIOException. It means the underlying directory could not be read while walking a filesystem-backed path tree, e.g. permissions or the directory disappearing mid-scan.

Source

Thrown at independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathTreeVisit.java:69

        return fs.getSeparator().equals("/") ? resourceName : resourceName.replace("/", fs.getSeparator());
    }

    static void walk(Path root, Path rootDir, Path walkDir, PathFilter pathFilter, Map<String, String> multiReleaseMapping,
            PathVisitor visitor) {
        final PathTreeVisit visit = new PathTreeVisit(root, rootDir, pathFilter, multiReleaseMapping);
        try (Stream<Path> files = Files.walk(walkDir)) {
            final Iterator<Path> i = files.iterator();
            while (i.hasNext()) {
                if (!visit.setCurrent(i.next())) {
                    continue;
                }
                visitor.visitPath(visit);
                if (visit.isStopWalking()) {
                    break;
                }
            }
        } catch (IOException e) {
            throw new UncheckedIOException("Failed to walk directory " + root, e);
        }
        visit.visitMultiReleasePaths(visitor);
    }

    static <T> T process(Path root, Path rootDir, Path path, PathFilter pathFilter, Function<PathVisit, T> func) {
        final PathTreeVisit visit = new PathTreeVisit(root, rootDir, pathFilter, Map.of());
        if (visit.setCurrent(path)) {
            return func.apply(visit);
        }
        return func.apply(null);
    }

    static void consume(Path root, Path rootDir, Path path, PathFilter pathFilter, Consumer<PathVisit> func) {
        final PathTreeVisit visit = new PathTreeVisit(root, rootDir, pathFilter, Map.of());
        if (visit.setCurrent(path)) {
            func.accept(visit);
        } else {
            func.accept(null);

View on GitHub (pinned to e1c734241f)

Solutions

Check the directory exists and is readable (ls/permissions) and recreate it (e.g. re-run build)
Re-run the application build so the classes directory is regenerated
Check for concurrent processes (IDE, another build) mutating the directory; avoid scanning while builds run
Inspect the cause chain (getCause) for the underlying IOException message

Defensive patterns

Strategy: try-catch

Validate before calling

Path dir = Path.of(root);
if (!Files.isDirectory(dir) || !Files.isReadable(dir)) { throw new IllegalStateException("Cannot walk: " + dir); }

Type guard

boolean isWalkableDir(Path p) { return Files.isDirectory(p) && Files.isReadable(p); }

Try / catch

try { walkInformationForPath(...); } catch (UncheckedIOException e) { log.error("Directory walk failed: " + e.getCause()); throw e; }

Prevention

Ensure class/output directories exist and are readable before scanning
Avoid scanning directories while builds/IDEs are mutating them
Run containers with correct volume permissions

When it happens

Trigger: Calling walk/visit on a directory-backed PathTree (e.g. classes directory) when Files.walkFileTree throws IOException: unreadable subdirectory (permissions), deleted/renamed directory during build, symlink loops, or I/O errors.

Common situations: Running in containers where the classes dir is mounted read-only or removed; IDE/build tool deleting output directory during a live-reload scan; OS-level permission issues after extraction.

Related errors

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