quarkusio/quarkus · error · ConfigurationException

quarkus.smallrye-openapi.path and quarkus.swagger-ui.path wa

Error message

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 [<path>].

What it means

Swagger UI and SmallRye OpenAPI both expose HTTP endpoints; each OpenAPI document path must differ from the UI path or routing becomes ambiguous. When an openapi document path equalsIgnoreCase the swagger-ui path, the build throws a ConfigurationException naming both the duplicate path and quarkus.swagger-ui.path.

Source

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

            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 ["
                                    + documentPath + "].",
                            Set.of(documentPath, "quarkus.swagger-ui.path"));
                }

                String openApiPath = devUIContextRoot
                        + nonApplicationRootPathBuildItem.resolvePath(documentPath);
                urls.put(documentName, openApiPath);
            });

            String swaggerUiPath = devUIContextRoot + nonApplicationRootPathBuildItem.resolvePath(swaggerUiConfig.path());
            ThemeHref theme = swaggerUiConfig.theme().orElse(ThemeHref.feeling_blue);

            NonApplicationRootPathBuildItem indexRootPathBuildItem = null;

            byte[] indexHtmlContent = generateIndexHtml(urls, swaggerUiPath, swaggerUiConfig,
                    indexRootPathBuildItem,
                    launchMode,

View on GitHub (pinned to e1c734241f)

Solutions

1. Change quarkus.swagger-ui.path (e.g. /swagger-ui) so it differs from the OpenAPI document path.
2. Or change quarkus.smallrye-openapi.path / documents.<name>.path to a unique value.
3. Remember the comparison is case-insensitive: /Swagger-UI still collides with /swagger-ui.

Example fix

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

// after
quarkus.smallrye-openapi.path=/api/openapi
quarkus.swagger-ui.path=/api/swagger-ui

// config lint before build
String ui = props.getProperty("quarkus.swagger-ui.path", "");
String api = props.getProperty("quarkus.smallrye-openapi.path", "");
if (ui.equalsIgnoreCase(api)) {
  throw new IllegalArgumentException("swagger-ui.path and smallrye-openapi.path must differ");
}

When it happens

Trigger: quarkus.smallrye-openapi.path (or a named document path in quarkus.smallrye-openapi.documents.<name>.path) set equal to quarkus.swagger-ui.path, case-insensitively.

Common situations: Both left at default-ish values like /q/openapi vs /q/swagger-ui then one edited to match; consolidating paths under a common prefix and accidentally colliding them.

Related errors

• quarkus.swagger-ui.path was set to "/", this is not allowed
• Failed to load application configuration
• Failed to initialize application configuration
• Unrecognized option for quarkus.bootstrap.misaligned-platfor
• The configuration ${clazz} is missing the @ConfigRoot annota

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