quarkusio/quarkus · error · IllegalStateException

Invalid configuration: `quarkus.management.port` must be dif

Error message

Invalid configuration: `quarkus.management.port` must be different from `quarkus.http.port`.

What it means

VertxHttpRecorder validates at startup that the management interface (quarkus.management.port) does not collide with the main HTTP port. Both servers would try to bind the same host/port, so the configuration is invalid and startup aborts with this IllegalStateException. Fixed, non-random ports are compared; 0 (random) is skipped.

Source

Thrown at extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/VertxHttpRecorder.java:1149

                auxiliaryApplication, httpManagementServerConfig);
    }

    private static void validateManagementPortDistinctFromMainServer(VertxHttpConfig httpConfig,
            ManagementInterfaceBuildTimeConfig managementBuildTimeConfig, ManagementConfig managementConfig,
            LaunchMode launchMode) {
        if (!managementBuildTimeConfig.enabled() || managementConfig == null || !managementConfig.hostEnabled()) {
            return;
        }

        int managementPort = managementConfig.determinePort(launchMode);
        if (managementPort <= 0) {
            // 0 means random port, so it can't be validated against fixed ports here
            return;
        }

        int httpPort = httpConfig.hostEnabled() ? httpConfig.determinePort(launchMode) : -1;
        if (httpPort > 0 && httpPort == managementPort) {
            throw new IllegalStateException(
                    "Invalid configuration: `quarkus.management.port` must be different from `quarkus.http.port`.");
        }

        int httpsPort = httpConfig.determineSslPort(launchMode);
        if (httpsPort > 0 && httpsPort == managementPort) {
            throw new IllegalStateException(
                    "Invalid configuration: `quarkus.management.port` must be different from `quarkus.http.ssl-port`.");
        }
    }

    private static void setHttpServerTiming(boolean httpDisabled, HttpServerConfig httpServerConfig,
            HttpServerConfig sslConfig,
            HttpServerConfig domainSocketConfig, boolean auxiliaryApplication, HttpServerConfig managementConfig) {
        StringBuilder serverListeningMessage = new StringBuilder("Listening on: ");
        int socketCount = 0;

        if (!httpDisabled && httpServerConfig != null) {
            serverListeningMessage.append(String.format(

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.management.port to a distinct value (e.g. 9000)
Or set quarkus.management.port=0 to pick a random free port
Check profile-specific config and environment-variable overrides for both properties

Example fix

// before
quarkus.http.port=8080
quarkus.management.port=8080
// after
quarkus.http.port=8080
quarkus.management.port=9000

Defensive patterns

Strategy: validation

Validate before calling

if (managementPort > 0 && managementPort == httpPort) {
    throw new IllegalStateException("quarkus.management.port must differ from quarkus.http.port");
}

Prevention

Assign management a dedicated port range (e.g. 9000+)
Check profile/env overrides for QUARKUS_MANAGEMENT_PORT and QUARKUS_HTTP_PORT
Use 0 (random) for the management port in tests

When it happens

Trigger: quarkus.management.port and the quarkus.determinePort-resolved quarkus.http.port resolve to the same positive integer while the management interface is enabled.

Common situations: Explicitly setting both properties to the same value (e.g. 8080); copying http config into management config; profile-specific overrides changed on one side only; QUARKUS_MANAGEMENT_PORT env var colliding.

Related errors

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