{"record":{"id":"f16eba97afba0048","repo":"quarkusio/quarkus","slug":"invalid-static-resource-path-path-paths-must","errorCode":null,"errorMessage":"Invalid static resource path '<path>'. Paths must not contain '..' when registering static resources.","messagePattern":"Invalid static resource path '<path>'\\. Paths must not contain '\\.\\.' when registering static resources\\.","errorType":"validation","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/VertxHttpProcessor.java","lineNumber":273,"sourceCode":"        if (dir == null) {\n            return;\n        }\n\n        Path root = Path.of(dir).normalize().toAbsolutePath();\n        if (!Files.isDirectory(root)) {\n            throw new IllegalStateException(\n                    \"Invalid configuration: quarkus.http.static-dir.path must point to an existing directory, but was: \"\n                            + root);\n        }\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();","sourceCodeStart":255,"sourceCodeEnd":291,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/VertxHttpProcessor.java#L255-L291","documentation":"After normalizing each file's path relative to the static root, the processor rejects any relative path containing '..'. A '..' segment after normalization means the resolved resource would escape the configured static directory (e.g. via symlinks or odd path components), a path-traversal risk. The build fails fast rather than registering an unsafe endpoint.","triggerScenarios":"A regular file under the static dir whose relativized+normalized path still contains '..' — typically caused by symlinked files/directories pointing outside the root, so root.relativize(file) yields segments like ../.. .","commonSituations":"Static directory contains symlinks to resources elsewhere in the project; shared assets linked from another module; CI checkouts with symlinked content.","solutions":["Replace symlinks with real copies of the files inside the static directory","Restructure the static dir so all content physically resides under it","Point quarkus.http.static-dir.path at the true root that contains all files so no relative path needs '..'"],"exampleFix":"// before (symlink escapes root)\nln -s ../../shared/logo.png static/logo.png\n// after\ncp ../../shared/logo.png static/logo.png","handlingStrategy":"validation","validationCode":"try (Stream<Path> files = Files.walk(staticRoot)) {\n    files.filter(Files::isRegularFile).forEach(f -> {\n        String rel = staticRoot.relativize(f).normalize().toString().replace('\\\\', '/');\n        if (rel.contains(\"..\")) {\n            throw new IllegalStateException(\"static dir contains path escaping root: \" + rel);\n        }\n    });\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Do not symlink files into the static directory; copy them instead","Run a pre-build script that checks for symlinks (find static-dir -type l) under the static root","Keep all served content physically inside the configured static directory"],"tags":["quarkus","vertx-http","static-resources","path-traversal","security"],"backgroundTag":"path-traversal-detected","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}