quarkusio/quarkus · error · java.io.UncheckedIOException

Failed to list content of

Error message

Failed to list content of 

What it means

DirectoryPathTree.isEmpty() lists the directory contents to determine whether the tree holds any entries. If the underlying directory cannot be listed (e.g. permission denied, it is not actually a directory, or it was deleted concurrently), the IOException is wrapped in an UncheckedIOException with this message. It is thrown from a boolean-looking API, so callers rarely expect it.

Source

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

    }

    @Override
    protected Path getContainerPath() {
        return dir;
    }

    @Override
    public boolean isOpen() {
        return true;
    }

    @Override
    public boolean isEmpty() {
        if (Files.exists(dir)) {
            try (Stream<Path> stream = Files.list(dir)) {
                return stream.findAny().isEmpty();
            } catch (IOException e) {
                throw new UncheckedIOException("Failed to list content of " + dir, e);
            }
        }
        return true;
    }

    @Override
    public void close() throws IOException {
    }

    @Override
    public PathTree getOriginalTree() {
        return this;
    }

    @Override
    public Set<String> getResourceNames() {
        return resourceNames == null ? resourceNames = super.getResourceNames() : resourceNames;
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Check OS permissions on the directory and ensure the process user can read it (ls -ld, chmod/chown).
2. Verify the path is actually a directory and still exists at call time; re-create the PathTree if the underlying path changed.
3. If the directory is on a network mount, check mount health and retry.
4. Catch UncheckedIOException at the call site and treat as 'cannot scan' if that is acceptable.

Example fix

// before
PathTree tree = PathTree.ofDirectoryOrFile(somePath, null);
boolean empty = tree.isEmpty(); // throws UncheckedIOException on unreadable dir
// after
if (!Files.isDirectory(somePath) || !Files.isReadable(somePath)) {
    throw new IllegalStateException("Directory missing or unreadable: " + somePath);
}
boolean empty = PathTree.ofDirectoryOrFile(somePath, null).isEmpty();

if (!Files.isDirectory(dir) || !Files.isReadable(dir)) {
    throw new IllegalStateException("Directory missing or unreadable: " + dir);
}

static boolean isListableDirectory(Path dir) {
    return dir != null && Files.isDirectory(dir) && Files.isReadable(dir);
}

try {
    boolean empty = tree.isEmpty();
} catch (UncheckedIOException e) {
    log.warnf("Cannot list %s: %s", dir, e.getCause());
    // treat as non-scannable
}

When it happens

Trigger: Calling isEmpty() on a DirectoryPathTree whose dir exists but cannot be opened by Files.list(): insufficient OS read permission, the path was replaced by a file/symlink to a file between Files.exists and Files.list, or an I/O error on a network/EFS mount.

Common situations: Running the app as a user without read access to a classpath directory; a hot-reload/dev-mode race where a directory is removed or recreated while Quarkus scans it; a mounted volume going offline.

Related errors

• Failed to create output directory for generated sources: %s
• IOException (wrapped)
• Unable to validate the application root for remote-dev path:
• Unable to validate remote-dev path: <file>
• Cannot create directory ${directory}

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