apache/skywalking · critical · IllegalStateException

admin-server: port must be > 0 when the module is enabled, g

Error message

admin-server: port must be > 0 when the module is enabled, got {port}

What it means

AdminServerModuleProvider.prepare() fails fast when the admin-server module is enabled but its HTTP port is unset or non-positive (<= 0). The admin HTTP server (GraphQL-ish admin queries, dsl-debugging REST endpoints) cannot start on an invalid port, so boot aborts with an IllegalStateException instead of a confusing bind failure later.

Source

Thrown at oap-server/server-admin/admin-server/src/main/java/org/apache/skywalking/oap/server/admin/server/module/AdminServerModuleProvider.java:99

    @Override
    public ConfigCreator newConfigCreator() {
        return new ConfigCreator<AdminServerModuleConfig>() {
            @Override
            public Class type() {
                return AdminServerModuleConfig.class;
            }

            @Override
            public void onInitialized(final AdminServerModuleConfig initialized) {
                moduleConfig = initialized;
            }
        };
    }

    @Override
    public void prepare() {
        if (moduleConfig.getPort() <= 0) {
            throw new IllegalStateException(
                "admin-server: port must be > 0 when the module is enabled, got "
                    + moduleConfig.getPort());
        }
        final HTTPServerConfig httpServerConfig =
            HTTPServerConfig.builder()
                            .host(Strings.isBlank(moduleConfig.getHost()) ? "0.0.0.0"
                                      : moduleConfig.getHost())
                            .port(moduleConfig.getPort())
                            .contextPath(moduleConfig.getContextPath())
                            .acceptQueueSize(moduleConfig.getAcceptQueueSize())
                            .idleTimeOut(moduleConfig.getIdleTimeOut())
                            .maxRequestHeaderSize(moduleConfig.getHttpMaxRequestHeaderSize())
                            .enableTLS(moduleConfig.isRestSSLEnabled())
                            .tlsKeyPath(moduleConfig.getRestSSLKeyPath())
                            .tlsCertChainPath(moduleConfig.getRestSSLCertChainPath())
                            .build();
        httpServer = new HTTPServer(httpServerConfig);
        httpServer.setBlockingTaskName("admin-http");

View on GitHub (pinned to 102af09b4a)

Solutions

1. Set a valid port under admin-server provider config in application.yml: admin-server: - selector: ${SW_ADMIN_SERVER} ... port: ${SW_ADMIN_SERVER_PORT:8092}
2. Or export SW_ADMIN_SERVER_PORT with a free, positive port on every OAP node
3. If you did not intend to run admin-server, remove the module selector / leave it disabled rather than setting a dummy port
4. Keep the port clear of the OAP gRPC (11800) and UI/query (12800) ports

Example fix

# before (application.yml)
admin-server:
  selector: ${SW_ADMIN_SERVER}
  default:
# after
admin-server:
  selector: ${SW_ADMIN_SERVER}
  default:
    port: ${SW_ADMIN_SERVER_PORT:8092}

# Pre-flight config check (shell) before starting OAP:
if [ "$SW_ADMIN_SERVER" = "default" ] && [ "${SW_ADMIN_SERVER_PORT:-0}" -le 0 ]; then
  echo "admin-server enabled but SW_ADMIN_SERVER_PORT unset/invalid"; exit 1;
fi

When it happens

Trigger: Enabling admin-server in application.yml (or via SW_MODULE_ADMIN_SERVER=...) without setting 'port' under the admin-server provider config, or setting port: 0 / a negative value. The module default is 0, so enabling without explicit config triggers it immediately.

Common situations: Turning on admin-server for dsl-debugging or admin cluster features in a custom application.yml copied from a template that lacks the port; overriding config via environment variables (SW_ADMIN_SERVER_PORT) but misspelling the variable; helm chart values not passing the port through.

Related errors

• admin-server: gRPCPort must be > 0 when the module is enable
• admin-server: gRPCSslEnabled=true but gRPCSslTrustedCAsPath
• decorate() should be invoked after service()
• Failed to compile MAL expression for metric: {}, expression:
• Some configuration files of enabled rules are not found, ena

AI-assisted analysis of apache/skywalking@102af09b4a (2026-08-14). Data as JSON: /api/errors/0f8edccea0e12b7e. Report an issue: GitHub.