quarkusio/quarkus · error · ConfigurationException

quarkus.swagger-ui.path was set to "/", this is not allowed

Error message

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

What it means

The Swagger UI extension serves its web jar under quarkus.swagger-ui.path. Setting that path to "/" would make the UI intercept every request, shadowing all application endpoints, so the build fails with a ConfigurationException listing the offending property.

Source

Thrown at extensions/swagger-ui/deployment/src/main/java/io/quarkus/swaggerui/deployment/SwaggerUiProcessor.java:99

                BRANDING_STYLE_MODULE,
                BRANDING_FAVICON_MODULE).map(HotDeploymentWatchedFileBuildItem::new)
                .collect(Collectors.toList());
    }

    @BuildStep
    public void getSwaggerUiFinalDestination(
            NonApplicationRootPathBuildItem nonApplicationRootPathBuildItem,
            Optional<DevContextBuildItem> devContextBuildItem,
            List<SwaggerUiUrlBuildItem> swaggerUiUrls,
            LaunchModeBuildItem launchMode,
            SwaggerUiConfig swaggerUiConfig,
            SmallRyeOpenApiConfig openapi,
            Optional<DevServicesLauncherConfigResultBuildItem> devServicesLauncherConfig,
            BuildProducer<WebJarBuildItem> webJarBuildProducer) throws Exception {

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

            String devUIContextRoot;
            if (devContextBuildItem.isPresent()) {
                devUIContextRoot = devContextBuildItem.get().getDevUIContextRoot();
            } else {
                devUIContextRoot = "";
            }

            Map<String, String> urls = new HashMap<>();
            openapi.documents().forEach((documentName, documentConfig) -> {
                String documentPath = documentConfig.path();

                if (documentPath.equalsIgnoreCase(swaggerUiConfig.path())) {
                    throw new ConfigurationException(
                            "quarkus.smallrye-openapi.path and quarkus.swagger-ui.path was set to the same value, this is not allowed as the paths needs to be unique ["

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.swagger-ui.path to a non-root path such as /swagger-ui or /api-docs-ui.
Serve Swagger UI at a distinct path and add a redirect route from / to it in your app if a root entry point is desired.
Disable the UI in production with quarkus.swagger-ui.include=true scoped to dev/test if unwanted.

Example fix

// before (application.properties)
quarkus.swagger-ui.path=/

// after
quarkus.swagger-ui.path=/swagger-ui

Defensive patterns

Strategy: validation

Validate before calling

// application.properties sanity check
if (props.getProperty("quarkus.swagger-ui.path", "").equals("/")) {
  throw new IllegalArgumentException("quarkus.swagger-ui.path must not be '/'");
}

Prevention

Never configure extension serving paths at "/"; reserve root for the app itself.
Use a redirect route in your own code if you want / to lead to the UI.

When it happens

Trigger: application.properties/yml containing quarkus.swagger-ui.path=/ (or equivalent), in a launch mode where the UI is included (shouldInclude).

Common situations: Trying to make the docs page the landing page; copy-pasting a config snippet without adjusting the path.

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/8d98a9f2c53af345. Report an issue: GitHub.