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

When a route build item is marked displayOnNotFoundPage(true), Quarkus must list it on the 'not found' page, which requires a concrete path to link to. getNotFoundEndpoint throws when the item relies solely on a route function (no routeConfigKey path and no notFoundPagePath) because there is no path to display. The routeFunction object is interpolated into the message purely for identification (it prints toString).

Source

Thrown at extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/NonApplicationRootPathBuildItem.java:420

        @Override
        protected ConfiguredPathInfo getRouteConfigInfo() {
            return super.getRouteConfigInfo();
        }

        @Override
        protected NotFoundPageDisplayableEndpointBuildItem getNotFoundEndpoint() {
            if (!displayOnNotFoundPage) {
                return null;
            }
            if (isManagement && buildItem.managementRootPath != null) {
                if (notFoundPagePath != null && absolutePath == null) {
                    absolutePath = getManagementUrlPrefix() + notFoundPagePath;
                } else {
                    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);
        }

        @Override
        public Builder management() {
            super.management();
            return this;
        }

        @Override
        public Builder management(String managementConfigKey) {
            super.management(managementConfigKey);
            return this;

View on GitHub (pinned to e1c734241f)

Solutions

Set an explicit path via notFoundPagePath(String) (or a routeConfigKey-backed routePath) on the builder so the 404 page has a link target
If the endpoint is dynamic/unnamed, remove displayOnNotFoundPage(true) since it cannot be listed
Use routeFunction(String route, Consumer<Route>) with the actual path and also set notFoundPagePath to that same path

Example fix

// before
builder.routeFunction("/q/metrics", r -> r.handler(h)).displayOnNotFoundPage(true);
// after
builder.route("quarkus.http.metrics.path", "/q/metrics").displayOnNotFoundPage(true);

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

boolean canDisplayOnNotFoundPage(NonApplicationRootPathBuildItem.Builder b) {
    // only paths backed by notFoundPagePath or a route config key can be listed
    return hasExplicitPath(b);
}

Prevention

Set notFoundPagePath whenever you call displayOnNotFoundPage(true)
Prefer config-key/path-based route registration for endpoints you want on the 404 page
Remember the 404 page links to static paths only — function-only routes cannot be listed

When it happens

Trigger: Calling NonApplicationRootPathBuildItem.Builder.displayOnNotFoundPage(true) and building the item while only a route function was registered via routeFunction(Function) or routeFunction(String,Consumer) with no explicit notFoundPagePath set, then invoking getNotFoundEndpoint during the build.

Common situations: Extension authors wanting a framework/console endpoint to appear on the 404 page but registering it with a Consumer<Route> route function instead of a config-key path; refactors that dropped route path configuration keys.

Related errors

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