quarkusio/quarkus · error · RuntimeException

Could not determine which StaticHandler to create.

Error message

Could not determine which StaticHandler to create.

What it means

WebJarStaticHandler lazily creates an underlying Vert.x StaticHandler on first request, deciding between a classpath (META-INF) handler and a file-system handler based on resolved destinations and configured web root locations. If neither source yields a usable configuration, it throws a RuntimeException stating it could not determine which StaticHandler to create.

Source

Thrown at extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/webjar/WebJarStaticHandler.java:86

            event.response().headers().set(HttpHeaders.LOCATION, path + "/");
            event.response().end();
            return;
        } else if (event.normalizedPath().length() == path.length() + 1) {
            event.reroute(path + "/index.html");
            return;
        }

        if (handler == null) {
            try {
                HANDLER_CREATION_LOCK.lock();
                if (handler == null) {
                    if (finalDestination != null && finalDestination.startsWith("META-INF")) {
                        handler = StaticHandler.create(finalDestination)
                                .setDefaultContentEncoding("UTF-8");
                    } else if (webRootConfigurations != null) {
                        handler = new FileSystemStaticHandler(webRootConfigurations);
                    } else {
                        throw new RuntimeException("Could not determine which StaticHandler to create.");
                    }
                }
            } finally {
                HANDLER_CREATION_LOCK.unlock();
            }
        }

        handler.handle(event);
    }

    @Override
    public void close() throws IOException {
        if (handler instanceof Closeable) {
            ((Closeable) handler).close();
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the WebJar dependency (e.g. org.webjars:jquery) to the project so META-INF/resources content exists.
2. Verify the requested URL matches the WebJar layout: /webjars/<artifact>/<version>/<path>.
3. Check packaging (e.g. native image or fat jar) includes META-INF/resources from the WebJar jar; add resources includes if needed.

Example fix

// before (pom.xml)
<!-- no webjar dependency -->
// after
<dependency>
  <groupId>org.webjars.npm</groupId>
  <artifactId>bootstrap-icons</artifactId>
  <version>1.11.3</version>
</dependency>

Class.forName("webjars.jquery"); // or: check classpath
URL u = Thread.currentThread().getContextClassLoader().getResource("META-INF/resources/webjars/<artifact>/<version>/");
if (u == null) throw new IllegalStateException("WebJar resource missing from classpath");

try {
  handler.handle(routingContext);
} catch (RuntimeException e) {
  if ("Could not determine which StaticHandler to create.".equals(e.getMessage())) {
    routingContext.response().setStatusCode(404).end();
  } else throw e;
}

When it happens

Trigger: Requesting a WebJar resource when neither the resolved final destination starts with 'META-INF' nor webRootConfigurations was populated — typically when the WebJar dependency is not on the classpath or no web roots are registered.

Common situations: Serving /webjars/... without the corresponding webjar Maven dependency included, or build/runtime packaging excluding META-INF/resources entries.

Related errors

• Failed to find any non-blocking provider for startup actions
• No Vert.x instance has been registered in ArC ?
• HttpBinderConfiguration was not found
• OpenTelemetryContextUnwrapper was not found
• No current Vertx context found

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