apache/skywalking · critical · IllegalStateException

admin-server: gRPCPort must be > 0 when the module is enable

Error message

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

What it means

AdminServerModuleProvider throws in start() when the admin-internal gRPC server is enabled but gRPCPort is <= 0. This is a separate, admin-only gRPC bus for peer-to-peer admin RPCs (dsl-debugging install/collect, runtime-rule Suspend/Resume/Forward), deliberately bound apart from the public agent/cluster port 11800 so privileged admin RPCs never share a blast radius with agent telemetry.

Source

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

                            .enableTLS(moduleConfig.isRestSSLEnabled())
                            .tlsKeyPath(moduleConfig.getRestSSLKeyPath())
                            .tlsCertChainPath(moduleConfig.getRestSSLCertChainPath())
                            .build();
        httpServer = new HTTPServer(httpServerConfig);
        httpServer.setBlockingTaskName("admin-http");
        httpServer.initialize();
        registerServiceImplementation(HTTPHandlerRegister.class,
                                      new HTTPHandlerRegisterImpl(httpServer));

        // Admin-internal gRPC server — peer-to-peer cluster RPCs for admin
        // features. Bound separately from the public agent / cluster gRPC
        // port (default 11800) so privileged admin RPCs (dsl-debugging
        // install/collect, runtime-rule Suspend/Resume/Forward) never share
        // a blast radius with agent telemetry. Operators bind this to a
        // private peer-to-peer interface; the cluster module dials each
        // peer at this port via AdminClusterChannelManager.
        if (moduleConfig.getGRPCPort() <= 0) {
            throw new IllegalStateException(
                "admin-server: gRPCPort must be > 0 when the module is enabled, got "
                    + moduleConfig.getGRPCPort());
        }
        if (moduleConfig.isGRPCSslEnabled()) {
            grpcServer = new GRPCServer(
                Strings.isBlank(moduleConfig.getGRPCHost()) ? "0.0.0.0" : moduleConfig.getGRPCHost(),
                moduleConfig.getGRPCPort(),
                moduleConfig.getGRPCSslCertChainPath(),
                moduleConfig.getGRPCSslKeyPath(),
                moduleConfig.getGRPCSslTrustedCAsPath());
        } else {
            grpcServer = new GRPCServer(
                Strings.isBlank(moduleConfig.getGRPCHost()) ? "0.0.0.0" : moduleConfig.getGRPCHost(),
                moduleConfig.getGRPCPort());
        }
        if (moduleConfig.getGRPCMaxConcurrentCallsPerConnection() > 0) {
            grpcServer.setMaxConcurrentCallsPerConnection(
                moduleConfig.getGRPCMaxConcurrentCallsPerConnection());

View on GitHub (pinned to 102af09b4a)

Solutions

1. Set gRPCPort to a positive, unused port under admin-server config, e.g. gRPCPort: ${SW_ADMIN_SERVER_GRPC_PORT:18080}
2. Ensure the port is reachable only between OAP nodes (private peer-to-peer interface) — it carries privileged admin RPCs and must not be exposed to the agent network
3. Avoid colliding with 11800 (agent gRPC), 12800 (UI HTTP) and the admin HTTP port

Example fix

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

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

When it happens

Trigger: admin-server module enabled with gRPCPort unset (default 0) or set non-positive in application.yml; or SW_ADMIN_SERVER_GRPC_PORT env var misspelled so the default 0 survives. The check fires at start(), after the HTTP config was accepted.

Common situations: Enabling admin-server after an upgrade that introduced the separate gRPC bus, while the old config only set the HTTP port; helm deployments where the new gRPC port value key was not added to values.yaml.

Related errors

• admin-server: port must be > 0 when the module is enabled, g
• admin-server: gRPCSslEnabled=true but gRPCSslTrustedCAsPath
• admin-server: failed to start gRPC server
• decorate() should be invoked after service()
• Failed to compile MAL expression for metric: {}, expression:

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