quarkusio/quarkus · error · ConfigurationException

quarkus.vertx-graphql.ui.path was set to "<path>", this is n

Error message

quarkus.vertx-graphql.ui.path was set to "<path>", this is not allowed as it blocks the application from serving anything else.

What it means

The Vert.x GraphQL UI extension requires its dedicated non-application root path. If quarkus.vertx-graphql.ui.path resolves to empty after removing trailing slashes/suffix (effectively '/'), the processor throws ConfigurationException because serving the UI at the root would swallow every route and prevent the application from serving anything else.

Source

Thrown at extensions/vertx-graphql/deployment/src/main/java/io/quarkus/vertx/graphql/deployment/VertxGraphqlProcessor.java:85

        return new NativeImageResourceDirectoryBuildItem("io/vertx/ext/web/handler/graphiql");
    }

    @BuildStep
    @Record(ExecutionTime.RUNTIME_INIT)
    void registerVertxGraphqlUI(VertxGraphqlRecorder recorder, VertxGraphqlConfig config,
            LaunchModeBuildItem launchMode, CoreVertxBuildItem coreVertxBuildItem,
            NonApplicationRootPathBuildItem nonApplicationRootPathBuildItem,
            BuildProducer<RouteBuildItem> routes,
            BodyHandlerBuildItem bodyHandler) {

        if (doNotIncludeVertxGraphqlUi(launchMode, config)) {
            return;
        }

        Matcher matcher = TRAILING_SLASH_SUFFIX_REGEX.matcher(config.ui().path());
        String path = matcher.replaceAll("");
        if (path.isEmpty()) {
            throw new ConfigurationException(
                    "quarkus.vertx-graphql.ui.path was set to \"" + config.ui().path()
                            + "\", this is not allowed as it blocks the application from serving anything else.");
        }

        Handler<RoutingContext> handler = recorder.handler(coreVertxBuildItem.getVertx());
        routes.produce(nonApplicationRootPathBuildItem.routeBuilder()
                .route(path)
                .handler(handler)
                .displayOnNotFoundPage("GraphQL UI")
                .build());
        routes.produce(
                nonApplicationRootPathBuildItem.routeBuilder()
                        .routeFunction(path + "/*", recorder.routeFunction(bodyHandler.getHandler()))
                        .handler(handler)
                        .build());
    }

    private static boolean doNotIncludeVertxGraphqlUi(LaunchModeBuildItem launchMode, VertxGraphqlConfig config) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Set a distinct path like quarkus.vertx-graphql.ui.path=graphql-ui
2. Remember the final URL includes the configured non-application root (quarkus.http.non-application-root-path)
3. Remove trailing slashes from the configured value

Example fix

// before
quarkus.vertx-graphql.ui.path=/

// after
quarkus.vertx-graphql.ui.path=graphql-ui

String uiPath = config.getOptionalValue("quarkus.vertx-graphql.ui.path", String.class).orElse("");
if (uiPath.replaceAll("/+$/, """).isEmpty()) {
    throw new IllegalArgumentException("quarkus.vertx-graphql.ui.path must not be / or empty");
}

When it happens

Trigger: Setting quarkus.vertx-graphql.ui.path=/ (or /ui/ with the regex stripping it to empty) at build time; VertxGraphqlProcessor.registerVertxGraphqlUI detects the empty resulting path and fails the build.

Common situations: Copying UI path configs between extensions; misunderstanding that the path is relative to the non-application root and setting it to '/'; typos leaving only slashes.

Related errors

• Unknown websocket subprotocol:
• quarkus.smallrye-graphql.root-path-ui was set to "/", this i
• Failed to load application configuration
• Failed to initialize application configuration
• Unrecognized option for quarkus.bootstrap.misaligned-platfor

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