quarkusio/quarkus · error · UncheckedIOException

java.io.UncheckedIOException

Error message

java.io.UncheckedIOException

What it means

PathTreeClassPathElement.apply opens the original PathTree to run a function and wraps any IOException in java.io.UncheckedIOException so it can be thrown from a lambda/supplier context. It signals that reading the backing filesystem tree failed while the element was being accessed. The message carries the wrapped IOException cause.

Source

Thrown at independent-projects/bootstrap/core/src/main/java/io/quarkus/bootstrap/classloading/PathTreeClassPathElement.java:143

            });
            return ret;
        });
    }

    @Override
    public <T> T apply(Function<OpenPathTree, T> func) {
        lock.readLock().lock();
        try {
            if (pathTree.isOpen()) {
                return func.apply(pathTree);
            }
            //we still need this to work if it is closed, so shutdown hooks work
            //once it is closed it simply does not hold on to any resources
            final boolean interrupted = Thread.interrupted();
            try (OpenPathTree openTree = pathTree.getOriginalTree().open()) {
                return func.apply(openTree);
            } catch (IOException e) {
                throw new UncheckedIOException(e);
            } finally {
                if (interrupted) {
                    Thread.currentThread().interrupt();
                }
            }
        } finally {
            lock.readLock().unlock();
        }
    }

    @Override
    public Set<String> getProvidedResources() {
        return pathTree.getResourceNames();
    }

    @Override
    public boolean containsReloadableResources() {
        return !pathTree.isArchiveOrigin();

View on GitHub (pinned to e1c734241f)

Solutions

1. Check the cause IOException for the real problem (missing file vs permission)
2. Ensure the application jars are not deleted/moved while running
3. Restore the missing classpath resource or rebuild the application
4. Retry on transient filesystem errors

Example fix

// before
byte[] data = element.getData(); // UncheckedIOException
// after
try {
    byte[] data = element.getData();
} catch (UncheckedIOException e) {
    LOGGER.error("Classpath element unreadable", e.getCause());
}

if (!Files.exists(pathTreeRoot)) throw new IllegalStateException("classpath element missing: " + pathTreeRoot);

try {
    byte[] data = element.getData();
} catch (UncheckedIOException e) {
    IOException cause = e.getCause();
    // log and fall back or abort startup
}

When it happens

Trigger: Calling methods on a PathTreeClassPathElement (via apply) after the underlying zip/file was deleted or moved, or when opening the PathTree throws IOException (I/O error reading the jar/file).

Common situations: Running application with jars removed while running (hot redeploys, cleanup scripts deleting target/), filesystem errors, or files locked on Windows.

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/774ce2e235fd60fc. Report an issue: GitHub.