{"record":{"id":"8f05d27f7a938315","repo":"quarkusio/quarkus","slug":"cannot-display-routefunction-on-not-found-page-a","errorCode":null,"errorMessage":"Cannot display <routeFunction> on not found page as no explicit path was specified and a route function is in use","messagePattern":"Cannot display <routeFunction> on not found page as no explicit path was specified and a route function is in use","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/NonApplicationRootPathBuildItem.java","lineNumber":420,"sourceCode":"        @Override\n        protected ConfiguredPathInfo getRouteConfigInfo() {\n            return super.getRouteConfigInfo();\n        }\n\n        @Override\n        protected NotFoundPageDisplayableEndpointBuildItem getNotFoundEndpoint() {\n            if (!displayOnNotFoundPage) {\n                return null;\n            }\n            if (isManagement && buildItem.managementRootPath != null) {\n                if (notFoundPagePath != null && absolutePath == null) {\n                    absolutePath = getManagementUrlPrefix() + notFoundPagePath;\n                } else {\n                    return null;\n                }\n            }\n            if (notFoundPagePath == null) {\n                throw new RuntimeException(\"Cannot display \" + routeFunction\n                        + \" on not found page as no explicit path was specified and a route function is in use\");\n            }\n            if (absolutePath != null) {\n                return new NotFoundPageDisplayableEndpointBuildItem(absolutePath, notFoundPageTitle, true);\n            }\n            return new NotFoundPageDisplayableEndpointBuildItem(notFoundPagePath, notFoundPageTitle, false);\n        }\n\n        @Override\n        public Builder management() {\n            super.management();\n            return this;\n        }\n\n        @Override\n        public Builder management(String managementConfigKey) {\n            super.management(managementConfigKey);\n            return this;","sourceCodeStart":402,"sourceCodeEnd":438,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx-http/deployment/src/main/java/io/quarkus/vertx/http/deployment/NonApplicationRootPathBuildItem.java#L402-L438","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nbuilder.routeFunction(\"/q/metrics\", r -> r.handler(h)).displayOnNotFoundPage(true);\n// after\nbuilder.route(\"quarkus.http.metrics.path\", \"/q/metrics\").displayOnNotFoundPage(true);","handlingStrategy":"validation","validationCode":"if (displayOnNotFoundPage && (notFoundPagePath == null || notFoundPagePath.isBlank())) {\n    throw new IllegalArgumentException(\"displayOnNotFoundPage requires notFoundPagePath\");\n}","typeGuard":"boolean canDisplayOnNotFoundPage(NonApplicationRootPathBuildItem.Builder b) {\n    // only paths backed by notFoundPagePath or a route config key can be listed\n    return hasExplicitPath(b);\n}","tryCatchPattern":null,"preventionTips":["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"],"tags":["quarkus","vertx-http","not-found-page","routing","build-time"],"backgroundTag":"missing-explicit-path","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}