{"record":{"id":"1f047461b6bacef9","repo":"apache/skywalking","slug":"zookeeper-namespace-cannot-be-null-or-empty","errorCode":null,"errorMessage":"Zookeeper namespace cannot be null or empty.","messagePattern":"Zookeeper namespace cannot be null or empty\\.","errorType":"exception","errorClass":"ModuleStartException","httpStatus":null,"severity":"critical","filePath":"oap-server/server-configuration/configuration-zookeeper/src/main/java/org/apache/skywalking/oap/server/configuration/zookeeper/ZookeeperConfigurationProvider.java","lineNumber":58,"sourceCode":"            @Override\n            public Class type() {\n                return ZookeeperServerSettings.class;\n            }\n\n            @Override\n            public void onInitialized(final ZookeeperServerSettings initialized) {\n                settings = initialized;\n            }\n        };\n    }\n\n    @Override\n    protected ConfigWatcherRegister initConfigReader() throws ModuleStartException {\n        if (Strings.isNullOrEmpty(settings.getHostPort())) {\n            throw new ModuleStartException(\"Zookeeper hostPort cannot be null or empty.\");\n        }\n        if (Strings.isNullOrEmpty(settings.getNamespace())) {\n            throw new ModuleStartException(\"Zookeeper namespace cannot be null or empty.\");\n        }\n\n        try {\n            return new ZookeeperConfigWatcherRegister(settings);\n        } catch (Exception e) {\n            throw new ModuleStartException(e.getMessage(), e);\n        }\n    }\n}\n","sourceCodeStart":40,"sourceCodeEnd":68,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-configuration/configuration-zookeeper/src/main/java/org/apache/skywalking/oap/server/configuration/zookeeper/ZookeeperConfigurationProvider.java#L40-L68","documentation":"Thrown by the ZooKeeper configuration provider at startup when the 'namespace' setting is null or empty. The namespace prefixes every znode path the provider reads (e.g. /namespace/config/...), so an empty namespace would collide with other users of the same ZooKeeper ensemble; the provider fails fast instead. It is checked right after hostPort in initConfigReader().","triggerScenarios":"Enabling configuration-zookeeper (or zookeeper cluster provider) with a hostPort configured but namespace absent, empty, or whitespace-stripped to empty by YAML parsing. The default in the shipped config is usually 'skywalking' or 'default' — removing it triggers this.","commonSituations":"Minimal hand-written application.yml that omits the namespace line; migration between SkyWalking versions where the example config changed; teams sharing a ZooKeeper cluster deleting the namespace intending to use root paths.","solutions":["Add namespace under the zookeeper block, e.g. namespace: skywalking","Check YAML indentation places namespace at the same level as hostPort","Restart OAP after the fix"],"exampleFix":"# before\nzookeeper:\n  hostPort: zk1:2181\n# namespace missing\n\n# after\nzookeeper:\n  hostPort: zk1:2181\n  namespace: skywalking","handlingStrategy":"validation","validationCode":"String ns = System.getenv().getOrDefault(\"SW_ZK_NAMESPACE\", \"\");\nif (ns == null || ns.trim().isEmpty()) {\n    throw new IllegalStateException(\"Configure zookeeper namespace before starting OAP\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat hostPort and namespace as one unit: a pre-flight check should validate both keys together","Use the same namespace across OAP nodes in a cluster so they read the same config znodes","Alert on OAP process exit within the first 30s of start — all *ConfigurationProvider failures are fail-fast"],"tags":["zookeeper","configuration","startup","oap-server"],"backgroundTag":null,"analyzedSha":"102af09b4a56064e22050dded10e2c52e490d040","analyzedAt":"2026-08-14T10:47:52.647Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}