quarkusio/quarkus · error · UncheckedIOException

Failed to register local static resources from directory

Error message

Failed to register local static resources from directory <root>

What it means

When walking the configured static directory throws IOException (permission denied, deleted mid-walk, I/O error), registerHttpStaticDir wraps it in UncheckedIOException with this message. The root directory existed (checked earlier) but could not be read. The original IOException is attached as the cause.

Solutions

Check and fix filesystem permissions (chmod/chown) so the build user can read the static directory and its contents
Ensure the directory is not concurrently modified/deleted during the build
Verify mounts/volumes in containers expose the directory correctly; retry the build after fixing the environment

Example fix

// before
chmod 600 static/            # build user cannot read
// after
chmod -R u+rX static/        # readable by the build user

Defensive patterns

Strategy: validation

Validate before calling

Path root = Path.of(staticDir).normalize().toAbsolutePath();
if (!Files.isDirectory(root) || !Files.isReadable(root)) {
    throw new IllegalStateException("static dir unreadable: " + root);
}
try (Stream<Path> s = Files.walk(root)) { s.count(); } // dry-run walk

Try / catch

try {
    registerStaticDir(root);
} catch (UncheckedIOException e) {
    // e.getCause() is the original IOException
    log.errorf("Cannot read static dir %s: %s", root, e.getCause());
    throw e;
}

Prevention

Ensure the build user has read+execute permissions on the static directory tree
Do not delete/modify the static directory while a build is running
In containers, verify volume mounts expose the directory before the build step executes

When it happens

Trigger: Files.walk(root) throwing IOException during the build step: unreadable directory permissions, files removed concurrently, filesystem/IO failure while traversing quarkus.http.static-dir.path.

Common situations: Static dir with restrictive permissions in CI containers; Docker/CI mounts that hide files mid-build; NFS or stale mounts; directory deleted between validation and walk.

Related errors

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

Appendix: source

Thrown at extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/VertxHttpProcessor.java:282

        }

        try (Stream<Path> paths = Files.walk(root)) {

            paths.filter(Files::isRegularFile).forEach(file -> {

                Path relative = root.relativize(file).normalize();
                String relativeUnix = relative.toString().replace('\\', '/');
                if (relativeUnix.contains("..")) {
                    throw new IllegalStateException("Invalid static resource path '" + relativeUnix
                            + "'. Paths must not contain '..' when registering static resources.");
                }
                String endpoint = basePath + "/" + relativeUnix;
                generatedStaticResources.produce(
                        new GeneratedStaticResourceBuildItem(endpoint, file));

            });
        } catch (IOException e) {
            throw new UncheckedIOException(
                    "Failed to register local static resources from directory " + root, e);
        }
    }

    @BuildStep(onlyIf = IsDevelopment.class)
    void watchHttpStaticDirForDev(VertxHttpBuildTimeConfig httpBuildTimeConfig,
            BuildProducer<HotDeploymentWatchedFileBuildItem> watchedFiles) {

        Optional<HttpStaticDirConfig> httpStaticDirConfig = httpBuildTimeConfig.httpStaticDirConfig();

        if (httpStaticDirConfig.isEmpty()) {
            return;
        }

        var localStatic = httpStaticDirConfig.get();

        if (!localStatic.enabled()) {
            return;

View on GitHub (pinned to e1c734241f)