quarkusio/quarkus · error · ConfigurationException

quarkus.smallrye-health.root-path-ui was set to "/", this is

Error message

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

What it means

When the health UI is included, its root path must not be '/', because the UI static handler would claim the entire application route space and shadow every other endpoint. If quarkus.smallrye-health.root-path-ui equals "/", the build step throws this ConfigurationException, additionally marking quarkus.smallrye-health.root-path-ui as the offending property.

Source

Thrown at extensions/smallrye-health/deployment/src/main/java/io/quarkus/smallrye/health/deployment/SmallRyeHealthProcessor.java:380

    @BuildStep
    ShutdownListenerBuildItem shutdownListener() {
        return new ShutdownListenerBuildItem(new ShutdownReadinessListener());
    }

    // UI
    @BuildStep
    void registerUiExtension(
            NonApplicationRootPathBuildItem nonApplicationRootPathBuildItem,
            ManagementInterfaceBuildTimeConfig managementBuildTimeConfig,
            SmallRyeHealthBuildTimeConfig healthConfig,
            LaunchModeBuildItem launchModeBuildItem,
            BuildProducer<WebJarBuildItem> webJarBuildProducer) {

        if (shouldInclude(launchModeBuildItem, healthConfig)) {

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

            String healthPath = nonApplicationRootPathBuildItem.resolveManagementPath(healthConfig.rootPath(),
                    managementBuildTimeConfig, launchModeBuildItem, false);

            webJarBuildProducer.produce(
                    WebJarBuildItem.builder().artifactKey(HEALTH_UI_WEBJAR_ARTIFACT_KEY) //
                            .root(HEALTH_UI_WEBJAR_STATIC_RESOURCES_PATH) //
                            .filter(new WebJarResourcesFilter() {
                                @Override
                                public FilterResult apply(String fileName, InputStream file) throws IOException {
                                    if (fileName.endsWith(JS_FILE_TO_UPDATE) || fileName.endsWith(INDEX_FILE_TO_UPDATE)) {
                                        byte[] content = SmallRyeHealthProcessor.this
                                                .updateApiUrl(new String(file.readAllBytes(), StandardCharsets.UTF_8),
                                                        healthPath)
                                                .getBytes(StandardCharsets.UTF_8);

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.smallrye-health.root-path-ui to a non-root path, e.g. /health-ui
Remove the property to fall back to the default UI path
Check environment variables and profiles for an override equal to "/"

Example fix

// before
quarkus.smallrye-health.root-path-ui=/

// after
quarkus.smallrye-health.root-path-ui=/health-ui

Defensive patterns

Strategy: validation

Validate before calling

String uiRoot = ConfigProvider.getConfig()
        .getValue("quarkus.smallrye-health.root-path-ui", String.class);
if ("/".equals(uiRoot)) {
    throw new IllegalArgumentException("root-path-ui must not be '/'");
}

Try / catch

try {
    startApplication();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("root-path-ui")) {
        throw new IllegalStateException("Set quarkus.smallrye-health.root-path-ui to a concrete path like /health-ui", e);
    }
    throw e;
}

Prevention

Never set any *-ui root path to '/' in Quarkus
Audit container env vars for overrides equal to "/"
Document the chosen UI path in your deployment manifest
Add a config validation test per profile

When it happens

Trigger: Setting quarkus.smallrye-health.root-path-ui=/ in application.properties (or via profile/env override) while the health UI is enabled (non-test modes where shouldInclude is true).

Common situations: Copying UI path config from another extension where '/' is legal; misunderstanding that root-path-ui is relative to the management/non-application root; setting it via environment variable QUARKUS_SMALLRYE_HEALTH_ROOT_PATH_UI=/ in containers.

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

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