quarkusio/quarkus · error · ConfigurationException

quarkus.smallrye-graphql.root-path-ui was set to "/", this i

Error message

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

What it means

SmallRyeGraphQLProcessor's UI build step rejects a UI root path of "/" because routing everything under the non-application root to the GraphQL UI would shadow all other application endpoints. It throws Quarkus ConfigurationException explicitly naming the offending property quarkus.smallrye-graphql.root-path-ui.

Source

Thrown at extensions/smallrye-graphql/deployment/src/main/java/io/quarkus/smallrye/graphql/deployment/SmallRyeGraphQLProcessor.java:1262

            // Auto dis/enable
            return linkedCapabilityIsPresent && activateByDefaultIfCapabilityIsPresent;
        }
    }

    // UI Related

    @BuildStep
    void getGraphqlUiFinalDestination(
            HttpRootPathBuildItem httpRootPath,
            NonApplicationRootPathBuildItem nonApplicationRootPathBuildItem,
            LaunchModeBuildItem launchMode,
            SmallRyeGraphQLConfig graphQLConfig,
            BuildProducer<WebJarBuildItem> webJarBuildProducer) {

        if (shouldInclude(launchMode, graphQLConfig)) {

            if ("/".equals(graphQLConfig.ui().rootPath())) {
                throw new ConfigurationException(
                        "quarkus.smallrye-graphql.root-path-ui was set to \"/\", this is not allowed as it blocks the application from serving anything else.",
                        Collections.singleton("quarkus.smallrye-graphql.root-path-ui"));
            }

            String graphQLPath = httpRootPath.resolvePath(graphQLConfig.rootPath());
            String graphQLUiPath = nonApplicationRootPathBuildItem.resolvePath(graphQLConfig.ui().rootPath());
            String devUiPath = nonApplicationRootPathBuildItem.resolvePath("dev");

            webJarBuildProducer.produce(
                    WebJarBuildItem.builder().artifactKey(GRAPHQL_UI_WEBJAR_ARTIFACT_KEY) //
                            .root(GRAPHQL_UI_WEBJAR_STATIC_RESOURCES_PATH) //
                            .filter(new WebJarResourcesFilter() {
                                @Override
                                public FilterResult apply(String fileName, InputStream file) throws IOException {
                                    if (fileName.endsWith(FILE_TO_UPDATE)) {
                                        String content = new String(file.readAllBytes(), StandardCharsets.UTF_8);
                                        content = updateUrl(content, graphQLPath, LINE_TO_UPDATE,
                                                LINE_FORMAT);

View on GitHub (pinned to e1c734241f)

Solutions

1. Set quarkus.smallrye-graphql.root-path-ui to a non-root path, e.g. /graphql-ui or /graphiql
2. Keep the API endpoint at quarkus.smallrye-graphql.root-path (e.g. /graphql) and only move the UI path — do not confuse the two properties
3. If the UI must be at '/', serve a custom redirect page yourself instead of relocating the UI route
4. Remove the property to fall back to the default UI root path

Example fix

// before
quarkus.smallrye-graphql.root-path-ui=/
// after
quarkus.smallrye-graphql.root-path-ui=/graphql-ui

// Validate the UI root path before building
String rootPathUi = System.getProperty("quarkus.smallrye-graphql.root-path-ui", "/graphql-ui");
if ("/".equals(rootPathUi)) {
    throw new IllegalArgumentException("quarkus.smallrye-graphql.root-path-ui cannot be '/' - choose e.g. /graphql-ui");
}

When it happens

Trigger: Setting quarkus.smallrye-graphql.root-path-ui=/ in application.properties (or the equivalent quarkus.smallrye-graphql.ui.root-path) and building/starting the application with the GraphQL UI included (non-test JVM or dev mode).

Common situations: Users wanting the UI at the site root mimicking hosted GraphQL playgrounds; copy-paste of config where root-path (GraphQL API) was intended instead of root-path-ui; misreading of root-path vs root-path-ui semantics.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• ${exposedEndpoint} is declared by :${endpointConfigs}
• Unknown websocket subprotocol:
• quarkus.vertx-graphql.ui.path was set to "<path>", this is n
• Failed to load application configuration
• Failed to initialize application configuration

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