{"record":{"id":"0f8edccea0e12b7e","repo":"apache/skywalking","slug":"admin-server-port-must-be-0-when-the-module-is","errorCode":null,"errorMessage":"admin-server: port must be > 0 when the module is enabled, got {port}","messagePattern":"admin-server: port 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":99,"sourceCode":"    @Override\n    public ConfigCreator newConfigCreator() {\n        return new ConfigCreator<AdminServerModuleConfig>() {\n            @Override\n            public Class type() {\n                return AdminServerModuleConfig.class;\n            }\n\n            @Override\n            public void onInitialized(final AdminServerModuleConfig initialized) {\n                moduleConfig = initialized;\n            }\n        };\n    }\n\n    @Override\n    public void prepare() {\n        if (moduleConfig.getPort() <= 0) {\n            throw new IllegalStateException(\n                \"admin-server: port must be > 0 when the module is enabled, got \"\n                    + moduleConfig.getPort());\n        }\n        final HTTPServerConfig httpServerConfig =\n            HTTPServerConfig.builder()\n                            .host(Strings.isBlank(moduleConfig.getHost()) ? \"0.0.0.0\"\n                                      : moduleConfig.getHost())\n                            .port(moduleConfig.getPort())\n                            .contextPath(moduleConfig.getContextPath())\n                            .acceptQueueSize(moduleConfig.getAcceptQueueSize())\n                            .idleTimeOut(moduleConfig.getIdleTimeOut())\n                            .maxRequestHeaderSize(moduleConfig.getHttpMaxRequestHeaderSize())\n                            .enableTLS(moduleConfig.isRestSSLEnabled())\n                            .tlsKeyPath(moduleConfig.getRestSSLKeyPath())\n                            .tlsCertChainPath(moduleConfig.getRestSSLCertChainPath())\n                            .build();\n        httpServer = new HTTPServer(httpServerConfig);\n        httpServer.setBlockingTaskName(\"admin-http\");","sourceCodeStart":81,"sourceCodeEnd":117,"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#L81-L117","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set a valid port under admin-server provider config in application.yml: admin-server: - selector: ${SW_ADMIN_SERVER} ... port: ${SW_ADMIN_SERVER_PORT:8092}","Or export SW_ADMIN_SERVER_PORT with a free, positive port on every OAP node","If you did not intend to run admin-server, remove the module selector / leave it disabled rather than setting a dummy port","Keep the port clear of the OAP gRPC (11800) and UI/query (12800) ports"],"exampleFix":"# before (application.yml)\nadmin-server:\n  selector: ${SW_ADMIN_SERVER}\n  default:\n# after\nadmin-server:\n  selector: ${SW_ADMIN_SERVER}\n  default:\n    port: ${SW_ADMIN_SERVER_PORT:8092}","handlingStrategy":"validation","validationCode":"# Pre-flight config check (shell) before starting OAP:\nif [ \"$SW_ADMIN_SERVER\" = \"default\" ] && [ \"${SW_ADMIN_SERVER_PORT:-0}\" -le 0 ]; then\n  echo \"admin-server enabled but SW_ADMIN_SERVER_PORT unset/invalid\"; exit 1;\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat enabling a module selector as a contract to fill in ALL its required settings — diff your application.yml against the shipped example when enabling admin-server","Use environment-variable interpolation with sane defaults (${SW_ADMIN_SERVER_PORT:8092}) so a missing env var cannot produce port 0"],"tags":["admin-server","configuration","startup","port"],"backgroundTag":null,"analyzedSha":"102af09b4a56064e22050dded10e2c52e490d040","analyzedAt":"2026-08-14T10:47:52.647Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}