apache/skywalking · critical · ModuleStartException

Zookeeper namespace cannot be null or empty.

Error message

Zookeeper namespace cannot be null or empty.

What it means

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().

Source

Thrown at oap-server/server-configuration/configuration-zookeeper/src/main/java/org/apache/skywalking/oap/server/configuration/zookeeper/ZookeeperConfigurationProvider.java:58

            @Override
            public Class type() {
                return ZookeeperServerSettings.class;
            }

            @Override
            public void onInitialized(final ZookeeperServerSettings initialized) {
                settings = initialized;
            }
        };
    }

    @Override
    protected ConfigWatcherRegister initConfigReader() throws ModuleStartException {
        if (Strings.isNullOrEmpty(settings.getHostPort())) {
            throw new ModuleStartException("Zookeeper hostPort cannot be null or empty.");
        }
        if (Strings.isNullOrEmpty(settings.getNamespace())) {
            throw new ModuleStartException("Zookeeper namespace cannot be null or empty.");
        }

        try {
            return new ZookeeperConfigWatcherRegister(settings);
        } catch (Exception e) {
            throw new ModuleStartException(e.getMessage(), e);
        }
    }
}

View on GitHub (pinned to 102af09b4a)

Solutions

1. Add namespace under the zookeeper block, e.g. namespace: skywalking
2. Check YAML indentation places namespace at the same level as hostPort
3. Restart OAP after the fix

Example fix

# before
zookeeper:
  hostPort: zk1:2181
# namespace missing

# after
zookeeper:
  hostPort: zk1:2181
  namespace: skywalking

String ns = System.getenv().getOrDefault("SW_ZK_NAMESPACE", "");
if (ns == null || ns.trim().isEmpty()) {
    throw new IllegalStateException("Configure zookeeper namespace before starting OAP");
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Zookeeper hostPort cannot be null or empty.
• Metric TTL should be at least 2 days, current value is {}
• Record TTL should be at least 2 days, current value is {}
• 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/1f047461b6bacef9. Report an issue: GitHub.