quarkusio/quarkus · error · IllegalStateException

Invalid static resource path '<path>'. Paths must not contai

Error message

Invalid static resource path '<path>'. Paths must not contain '..' when registering static resources.

What it means

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.

Source

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

        if (dir == null) {
            return;
        }

        Path root = Path.of(dir).normalize().toAbsolutePath();
        if (!Files.isDirectory(root)) {
            throw new IllegalStateException(
                    "Invalid configuration: quarkus.http.static-dir.path must point to an existing directory, but was: "
                            + root);
        }

        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();

View on GitHub (pinned to e1c734241f)

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 '..'

Example fix

// before (symlink escapes root)
ln -s ../../shared/logo.png static/logo.png
// after
cp ../../shared/logo.png static/logo.png

Defensive patterns

Strategy: validation

Validate before calling

try (Stream<Path> files = Files.walk(staticRoot)) {
    files.filter(Files::isRegularFile).forEach(f -> {
        String rel = staticRoot.relativize(f).normalize().toString().replace('\\', '/');
        if (rel.contains("..")) {
            throw new IllegalStateException("static dir contains path escaping root: " + rel);
        }
    });
}

Prevention

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

When it happens

Trigger: 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 ../.. .

Common situations: Static directory contains symlinks to resources elsewhere in the project; shared assets linked from another module; CI checkouts with symlinked content.

Related errors

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