quarkusio/quarkus · error · UncheckedIOException

Failed to register local static resources from directory <ro

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.

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)

Solutions

1. Check and fix filesystem permissions (chmod/chown) so the build user can read the static directory and its contents
2. Ensure the directory is not concurrently modified/deleted during the build
3. 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

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 {
    registerStaticDir(root);
} catch (UncheckedIOException e) {
    // e.getCause() is the original IOException
    log.errorf("Cannot read static dir %s: %s", root, e.getCause());
    throw e;
}

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

• Invalid configuration: quarkus.http.static-dir.path must poi
• This method is not supported using this builder. Use #routeF
• Cannot display <routeFunction> on not found page as no expli
• 'RouteBuildItem$Builder.routeFunction' was not set. Ensure t
• Cannot discover value of <routeConfigKey> as no explicit pat

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