quarkusio/quarkus · error · IllegalStateException

'RouteBuildItem$Builder.routeFunction' was not set. Ensure t

Error message

'RouteBuildItem$Builder.routeFunction' was not set. Ensure that one of the builder methods that result in it being set is called

What it means

RouteBuildItem.Builder.build() is a state-machine guard: it refuses to produce a RouteBuildItem whose routeFunction field is null, since such an item would render a route with no handler. The builder offers several setters (route(), routeFunction(), orderedRoute(), etc.) and at least one must have been invoked. Throwing IllegalStateException at build-time surfaces the misconfigured builder to the extension author immediately.

Source

Thrown at extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/RouteBuildItem.java:255

        }

        public Builder management(String managementConfigKey) {
            if (managementConfigKey == null || shouldInclude(managementConfigKey)) {
                this.isManagement = true;
            } else {
                this.isManagement = false;
            }
            return this;
        }

        private boolean shouldInclude(String managementConfigKey) {
            Config config = ConfigProvider.getConfig();
            return config.getValue(managementConfigKey, boolean.class);
        }

        public RouteBuildItem build() {
            if (routeFunction == null) {
                throw new IllegalStateException(
                        "'RouteBuildItem$Builder.routeFunction' was not set. Ensure that one of the builder methods that result in it being set is called");
            }
            return new RouteBuildItem(this, APPLICATION_ROUTE, APPLICATION_ROUTE, isManagement);
        }

        protected ConfiguredPathInfo getRouteConfigInfo() {
            if (routeConfigKey == null) {
                return null;
            }
            if (routePath == null) {
                throw new RuntimeException("Cannot discover value of " + routeConfigKey
                        + " as no explicit path was specified and a route function is in use");
            }
            if (absolutePath != null) {
                return new ConfiguredPathInfo(routeConfigKey, absolutePath, true, isManagement);
            }
            return new ConfiguredPathInfo(routeConfigKey, routePath, false, isManagement);
        }

View on GitHub (pinned to e1c734241f)

Solutions

Call a route-producing method before build(): builder.routeFunction("/path", route -> route.handler(handler)).build()
If the route is conditional, guard the whole builder creation rather than building an empty builder
Inspect your builder chain: every build() call must be preceded by exactly the route setup

Example fix

// before
RouteBuildItem item = new RouteBuildItem.Builder().displayOnNotFoundPage(true).build();
// after
RouteBuildItem item = new RouteBuildItem.Builder()
    .routeFunction("/q/health", r -> r.handler(myHandler))
    .displayOnNotFoundPage(true)
    .build();

Defensive patterns

Strategy: validation

Validate before calling

RouteBuildItem.Builder b = new RouteBuildItem.Builder()...;
Objects.requireNonNull(routeHandler, "handler must be set before build()");
RouteBuildItem item = b.routeFunction(path, r -> r.handler(routeHandler)).build();

Prevention

Make the routeFunction(...) call immediately precede build() in every builder chain
Return the builder from a helper that always sets the handler, so an empty builder cannot be built
If route creation is conditional, conditionally return null instead of building an unconfigured builder

When it happens

Trigger: Calling build() on a RouteBuildItem.Builder without having called any of route(), routeFunction(), orderedRoute(), or another method that populates routeFunction — e.g. a builder created and configured only with displayOnNotFoundPage or route config key.

Common situations: Constructing a builder and forgetting the handler step after setting metadata; conditionally skipping the route/handler call due to a null handler bean; copy-pasting a builder chain and deleting the route(...) line.

Related errors

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