{"record":{"id":"be22a5198cab0744","repo":"quarkusio/quarkus","slug":"could-not-determine-which-statichandler-to-create","errorCode":null,"errorMessage":"Could not determine which StaticHandler to create.","messagePattern":"Could not determine which StaticHandler to create\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/webjar/WebJarStaticHandler.java","lineNumber":86,"sourceCode":"            event.response().headers().set(HttpHeaders.LOCATION, path + \"/\");\n            event.response().end();\n            return;\n        } else if (event.normalizedPath().length() == path.length() + 1) {\n            event.reroute(path + \"/index.html\");\n            return;\n        }\n\n        if (handler == null) {\n            try {\n                HANDLER_CREATION_LOCK.lock();\n                if (handler == null) {\n                    if (finalDestination != null && finalDestination.startsWith(\"META-INF\")) {\n                        handler = StaticHandler.create(finalDestination)\n                                .setDefaultContentEncoding(\"UTF-8\");\n                    } else if (webRootConfigurations != null) {\n                        handler = new FileSystemStaticHandler(webRootConfigurations);\n                    } else {\n                        throw new RuntimeException(\"Could not determine which StaticHandler to create.\");\n                    }\n                }\n            } finally {\n                HANDLER_CREATION_LOCK.unlock();\n            }\n        }\n\n        handler.handle(event);\n    }\n\n    @Override\n    public void close() throws IOException {\n        if (handler instanceof Closeable) {\n            ((Closeable) handler).close();\n        }\n    }\n}\n","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/webjar/WebJarStaticHandler.java#L68-L104","documentation":"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.","triggerScenarios":"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.","commonSituations":"Serving /webjars/... without the corresponding webjar Maven dependency included, or build/runtime packaging excluding META-INF/resources entries.","solutions":["Add the WebJar dependency (e.g. org.webjars:jquery) to the project so META-INF/resources content exists.","Verify the requested URL matches the WebJar layout: /webjars/<artifact>/<version>/<path>.","Check packaging (e.g. native image or fat jar) includes META-INF/resources from the WebJar jar; add resources includes if needed."],"exampleFix":"// before (pom.xml)\n<!-- no webjar dependency -->\n// after\n<dependency>\n  <groupId>org.webjars.npm</groupId>\n  <artifactId>bootstrap-icons</artifactId>\n  <version>1.11.3</version>\n</dependency>","handlingStrategy":"fallback","validationCode":"Class.forName(\"webjars.jquery\"); // or: check classpath\nURL u = Thread.currentThread().getContextClassLoader().getResource(\"META-INF/resources/webjars/<artifact>/<version>/\");\nif (u == null) throw new IllegalStateException(\"WebJar resource missing from classpath\");","typeGuard":null,"tryCatchPattern":"try {\n  handler.handle(routingContext);\n} catch (RuntimeException e) {\n  if (\"Could not determine which StaticHandler to create.\".equals(e.getMessage())) {\n    routingContext.response().setStatusCode(404).end();\n  } else throw e;\n}","preventionTips":["Add all required org.webjars dependencies explicitly","Verify native/fat-jar packaging includes META-INF/resources","Smoke-test /webjars/<artifact>/<version>/ URLs after build"],"tags":["quarkus","vertx","static-resources","webjar"],"backgroundTag":"static-handler-unresolved","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"}