quarkusio/quarkus · error · IllegalStateException

Invalid configuration: quarkus.http.static-dir.path must poi

Error message

Invalid configuration: quarkus.http.static-dir.path must point to an existing directory, but was: <root>

What it means

VertxHttpProcessor.registerHttpStaticDir runs when quarkus.http.static-dir.path is set, serving files from the local filesystem as generated static resources at build time. Before walking the directory it verifies the configured value is an actual directory; if not it fails the build with IllegalStateException. This guards against typos or wrong working directories producing an empty/broken resource set.

Source

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

            return;
        }

        HttpStaticDirConfig localStatic = httpStaticDirConfig.get();

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

        final String basePath = localStatic.normalizedEndpoint();
        String dir = localStatic.normalizedPath();

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

View on GitHub (pinned to e1c734241f)

Solutions

1. Fix quarkus.http.static-dir.path to point to an existing directory (the message shows the resolved absolute path 'root' — verify it matches intent)
2. Use an absolute path or one correct relative to the build's working directory
3. If the directory is generated, ensure the generating step/ordering runs before this build step or pre-create it

Example fix

// application.properties
// before
quarkus.http.static-dir.path=src/main/resources/static-files  # does not exist in build cwd
// after
quarkus.http.static-dir.path=src/main/resources/META-INF/resources/static-files

String dir = ConfigProvider.getConfig()
    .getValue("quarkus.http.static-dir.path", String.class);
Path root = Path.of(dir).normalize().toAbsolutePath();
if (!Files.isDirectory(root)) {
    throw new IllegalStateException("static-dir must be an existing directory: " + root);
}

When it happens

Trigger: Setting quarkus.http.static-dir.path to a non-existent path, a file (not directory), or a path relative to a working directory different from the one the build runs in.

Common situations: Relative path configured that resolves differently on CI vs local; path points at a file like public/index.html instead of the directory public; path created after the build step runs (e.g. generated by another plugin).

Related errors

• Failed to register local static resources from directory <ro
• The configuration ${clazz} is missing the @ConfigRoot annota
• Invalid configuration value set for 'quarkus.arc.remove-unus
• Hibernate Envers activated explicitly for persistence unit '
• The FastbootHibernateProvider PersistenceProvider can not su

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