{"record":{"id":"e47147f0b66bbf92","repo":"quarkusio/quarkus","slug":"failed-to-register-local-static-resources-from-dir","errorCode":null,"errorMessage":"Failed to register local static resources from directory <root>","messagePattern":"Failed to register local static resources from directory <root>","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"error","filePath":"extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/VertxHttpProcessor.java","lineNumber":282,"sourceCode":"        }\n\n        try (Stream<Path> paths = Files.walk(root)) {\n\n            paths.filter(Files::isRegularFile).forEach(file -> {\n\n                Path relative = root.relativize(file).normalize();\n                String relativeUnix = relative.toString().replace('\\\\', '/');\n                if (relativeUnix.contains(\"..\")) {\n                    throw new IllegalStateException(\"Invalid static resource path '\" + relativeUnix\n                            + \"'. Paths must not contain '..' when registering static resources.\");\n                }\n                String endpoint = basePath + \"/\" + relativeUnix;\n                generatedStaticResources.produce(\n                        new GeneratedStaticResourceBuildItem(endpoint, file));\n\n            });\n        } catch (IOException e) {\n            throw new UncheckedIOException(\n                    \"Failed to register local static resources from directory \" + root, e);\n        }\n    }\n\n    @BuildStep(onlyIf = IsDevelopment.class)\n    void watchHttpStaticDirForDev(VertxHttpBuildTimeConfig httpBuildTimeConfig,\n            BuildProducer<HotDeploymentWatchedFileBuildItem> watchedFiles) {\n\n        Optional<HttpStaticDirConfig> httpStaticDirConfig = httpBuildTimeConfig.httpStaticDirConfig();\n\n        if (httpStaticDirConfig.isEmpty()) {\n            return;\n        }\n\n        var localStatic = httpStaticDirConfig.get();\n\n        if (!localStatic.enabled()) {\n            return;","sourceCodeStart":264,"sourceCodeEnd":300,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/VertxHttpProcessor.java#L264-L300","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nchmod 600 static/            # build user cannot read\n// after\nchmod -R u+rX static/        # readable by the build user","handlingStrategy":"validation","validationCode":"Path root = Path.of(staticDir).normalize().toAbsolutePath();\nif (!Files.isDirectory(root) || !Files.isReadable(root)) {\n    throw new IllegalStateException(\"static dir unreadable: \" + root);\n}\ntry (Stream<Path> s = Files.walk(root)) { s.count(); } // dry-run walk","typeGuard":null,"tryCatchPattern":"try {\n    registerStaticDir(root);\n} catch (UncheckedIOException e) {\n    // e.getCause() is the original IOException\n    log.errorf(\"Cannot read static dir %s: %s\", root, e.getCause());\n    throw e;\n}","preventionTips":["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"],"tags":["quarkus","vertx-http","static-resources","io-error","build-time"],"backgroundTag":"io-error-permission-denied","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}