quarkusio/quarkus · error · RuntimeException

This method is not supported using this builder. Use #routeF

Error message

This method is not supported using this builder. Use #routeFunction(String, Consumer<Route>)

What it means

The Builder obtained from HttpRootPathBuildItem.routeBuilder() deliberately forbids the inherited routeFunction(Function<Router, Route>) overload because raw router access would bypass the resolved root path handling. Calling it throws RuntimeException directing developers to the root-path-aware routeFunction(String, Consumer<Route>) variant.

Source

Thrown at extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/HttpRootPathBuildItem.java:116

    }

    public HttpRootPathBuildItem.Builder routeBuilder() {
        return new HttpRootPathBuildItem.Builder(this);
    }

    public static class Builder extends RouteBuildItem.Builder {
        private final HttpRootPathBuildItem buildItem;
        private RouteType routeType = RouteType.APPLICATION_ROUTE;
        private RouteType routerType = RouteType.APPLICATION_ROUTE;
        private String path;

        private Builder(HttpRootPathBuildItem buildItem) {
            this.buildItem = buildItem;
        }

        @Override
        public Builder routeFunction(Function<Router, Route> routeFunction) {
            throw new RuntimeException(
                    "This method is not supported using this builder. Use #routeFunction(String, Consumer<Route>)");
        }

        public Builder orderedRoute(String route, Integer order) {
            route = super.absolutePath = buildItem.resolvePath(route);

            if (route.startsWith(buildItem.getRootPath())) {
                // relative to http root (leading slash for vert.x route)
                this.path = "/" + UriNormalizationUtil.relativize(buildItem.getRootPath(), route);
                this.routerType = RouteType.APPLICATION_ROUTE;
            } else if (route.startsWith("/")) {
                // absolute path
                this.path = route;
                this.routerType = RouteType.ABSOLUTE_ROUTE;
            }

            BasicRoute basicRoute = new BasicRoute(this.path, order);

View on GitHub (pinned to e1c734241f)

Solutions

Use routeFunction(String path, Consumer<Route> consumer) on the builder instead
Pass the route path relative to the root and configure the Route inside the Consumer
If raw router manipulation is truly needed, produce a RouteBuildItem directly rather than via HttpRootPathBuildItem.routeBuilder()

Example fix

// before
buildItem.routeBuilder().routeFunction(router -> router.route("/x").handler(h));

// after
buildItem.routeBuilder().routeFunction("/x", route -> route.handler(h));

Defensive patterns

Strategy: validation

Validate before calling

// Only call routeFunction(Function) on objects explicitly typed as RouteBuildItem.Builder,
// never on HttpRootPathBuildItem.routeBuilder() results.
// Prefer: builder.routeFunction(String path, Consumer<Route> consumer)

Prevention

Always use the String path + Consumer<Route> overload with root-path builders
Wrap common route registration into helpers taking (path, Consumer<Route>)
Keep route registration code written against plain Router separate from HttpRootPathBuildItem-based code

When it happens

Trigger: Calling buildItem.routeBuilder().routeFunction(router -> router.route(...)) on the HttpRootPathBuildItem-provided Builder; the override throws immediately at build time.

Common situations: Copy-pasting route registration code written against the plain RouteBuildItem/Router API and reusing it inside an HttpRootPathBuildItem builder; migrating code that previously used a raw Router and now builds routes relative to the configured root path.

Related errors

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