quarkusio/quarkus · error · RuntimeException

Cannot display <routeFunction> on not found page as no expli

Error message

Cannot display <routeFunction> on not found page as no explicit path was specified and a route function is in use

What it means

Identical contract to the NonApplicationRootPathBuildItem variant: displayOnNotFoundPage requires a linkable path. RouteBuildItem.getNotFoundEndpoint throws when displayOnNotFoundPage is true but notFoundPagePath is null — i.e. the route was registered purely as a function with no explicit path to render on the 404 page. The routeFunction is stringified into the message only for diagnostics.

Source

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

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

        protected NotFoundPageDisplayableEndpointBuildItem getNotFoundEndpoint() {
            if (!displayOnNotFoundPage) {
                return null;
            }
            if (notFoundPagePath == null) {
                throw new RuntimeException("Cannot display " + routeFunction
                        + " on not found page as no explicit path was specified and a route function is in use");
            }
            if (absolutePath != null) {
                return new NotFoundPageDisplayableEndpointBuildItem(absolutePath, notFoundPageTitle, true);
            }
            return new NotFoundPageDisplayableEndpointBuildItem(notFoundPagePath, notFoundPageTitle, false);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Call notFoundPagePath("/your/path") on the builder so the 404 page can link to it
2. Remove displayOnNotFoundPage(true) if the endpoint cannot have a static path
3. Register with a path-aware method (route(configKey, path)) instead of the bare function

Example fix

// before
new RouteBuildItem.Builder().routeFunction("/q/x", r -> r.handler(h)).displayOnNotFoundPage(true);
// after
new RouteBuildItem.Builder().routeFunction("/q/x", r -> r.handler(h))
    .displayOnNotFoundPage(true).notFoundPagePath("/q/x");

if (displayOnNotFoundPage && notFoundPagePath == null) {
    throw new IllegalArgumentException("displayOnNotFoundPage(true) requires notFoundPagePath");
}

When it happens

Trigger: RouteBuildItem.Builder with displayOnNotFoundPage(true) and no notFoundPagePath/routePath (route registered via routeFunction), then getNotFoundEndpoint() is called during the not-found-page build step.

Common situations: Dev-mode endpoints (e.g. Dev UI routes) marked for display on the 404 page but defined with Consumer<Route> handlers; migrating from path-based to function-based route registration.

Related errors

• Cannot display <routeFunction> on not found page as no expli
• This method is not supported using this builder. Use #routeF
• 'RouteBuildItem$Builder.routeFunction' was not set. Ensure t
• Cannot discover value of <routeConfigKey> as no explicit pat
• Too many default routes.

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