{"record":{"id":"23e02d4f076e7e4a","repo":"apache/skywalking","slug":"admin-server-grpcport-must-be-0-when-the-module","errorCode":null,"errorMessage":"admin-server: gRPCPort must be > 0 when the module is enabled, got {gRPCPort}","messagePattern":"admin-server: gRPCPort must be > 0 when the module is enabled, got (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"oap-server/server-admin/admin-server/src/main/java/org/apache/skywalking/oap/server/admin/server/module/AdminServerModuleProvider.java","lineNumber":130,"sourceCode":"                            .enableTLS(moduleConfig.isRestSSLEnabled())\n                            .tlsKeyPath(moduleConfig.getRestSSLKeyPath())\n                            .tlsCertChainPath(moduleConfig.getRestSSLCertChainPath())\n                            .build();\n        httpServer = new HTTPServer(httpServerConfig);\n        httpServer.setBlockingTaskName(\"admin-http\");\n        httpServer.initialize();\n        registerServiceImplementation(HTTPHandlerRegister.class,\n                                      new HTTPHandlerRegisterImpl(httpServer));\n\n        // Admin-internal gRPC server — peer-to-peer cluster RPCs for admin\n        // features. Bound separately from the public agent / cluster gRPC\n        // port (default 11800) so privileged admin RPCs (dsl-debugging\n        // install/collect, runtime-rule Suspend/Resume/Forward) never share\n        // a blast radius with agent telemetry. Operators bind this to a\n        // private peer-to-peer interface; the cluster module dials each\n        // peer at this port via AdminClusterChannelManager.\n        if (moduleConfig.getGRPCPort() <= 0) {\n            throw new IllegalStateException(\n                \"admin-server: gRPCPort must be > 0 when the module is enabled, got \"\n                    + moduleConfig.getGRPCPort());\n        }\n        if (moduleConfig.isGRPCSslEnabled()) {\n            grpcServer = new GRPCServer(\n                Strings.isBlank(moduleConfig.getGRPCHost()) ? \"0.0.0.0\" : moduleConfig.getGRPCHost(),\n                moduleConfig.getGRPCPort(),\n                moduleConfig.getGRPCSslCertChainPath(),\n                moduleConfig.getGRPCSslKeyPath(),\n                moduleConfig.getGRPCSslTrustedCAsPath());\n        } else {\n            grpcServer = new GRPCServer(\n                Strings.isBlank(moduleConfig.getGRPCHost()) ? \"0.0.0.0\" : moduleConfig.getGRPCHost(),\n                moduleConfig.getGRPCPort());\n        }\n        if (moduleConfig.getGRPCMaxConcurrentCallsPerConnection() > 0) {\n            grpcServer.setMaxConcurrentCallsPerConnection(\n                moduleConfig.getGRPCMaxConcurrentCallsPerConnection());","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-admin/admin-server/src/main/java/org/apache/skywalking/oap/server/admin/server/module/AdminServerModuleProvider.java#L112-L148","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set gRPCPort to a positive, unused port under admin-server config, e.g. gRPCPort: ${SW_ADMIN_SERVER_GRPC_PORT:18080}","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","Avoid colliding with 11800 (agent gRPC), 12800 (UI HTTP) and the admin HTTP port"],"exampleFix":"# before (application.yml)\nadmin-server:\n  selector: ${SW_ADMIN_SERVER}\n  default:\n    port: ${SW_ADMIN_SERVER_PORT:8092}\n# after\nadmin-server:\n  selector: ${SW_ADMIN_SERVER}\n  default:\n    port: ${SW_ADMIN_SERVER_PORT:8092}\n    gRPCPort: ${SW_ADMIN_SERVER_GRPC_PORT:18080}","handlingStrategy":"validation","validationCode":"# Pre-flight config check (shell):\nif [ \"$SW_ADMIN_SERVER\" = \"default\" ] && [ \"${SW_ADMIN_SERVER_GRPC_PORT:-0}\" -le 0 ]; then\n  echo \"admin-server enabled but SW_ADMIN_SERVER_GRPC_PORT unset/invalid\"; exit 1;\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["After upgrading SkyWalking, re-read the admin-server config section — new sub-services (like the peer gRPC bus) add new required keys","Give the admin gRPC port a distinct value from 11800/12800 and expose it only on the OAP peer network"],"tags":["admin-server","configuration","startup","grpc","port"],"backgroundTag":null,"analyzedSha":"102af09b4a56064e22050dded10e2c52e490d040","analyzedAt":"2026-08-14T10:47:52.647Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}