apache/skywalking · critical · ModuleStartException

Zookeeper hostPort cannot be null or empty.

Error message

Zookeeper hostPort cannot be null or empty.

What it means

This ModuleStartException is thrown by the ZooKeeper configuration provider during OAP startup when the 'hostPort' setting of the cluster/configuration ZooKeeper connection is null or empty (checked with Guava Strings.isNullOrEmpty). The provider refuses to build a ZookeeperConfigWatcherRegister because a Curator client cannot connect without a target address. It is a fail-fast boot-time validation error, not a runtime connectivity error.

Source

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

    @Override
    public ConfigCreator newConfigCreator() {
        return new ConfigCreator<ZookeeperServerSettings>() {
            @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. Set cluster/configuration zookeeper hostPort in application.yml, e.g. hostPort: zk1:2181,zk2:2181,zk3:2181
2. Verify YAML indentation so hostPort sits directly under the zookeeper settings block
3. If using env substitution (${SW_ZK_HOSTPORT}), confirm the variable is exported and non-empty in the launch environment
4. After fixing, restart OAP — the error is boot-time only

Example fix

# before (application.yml)
configuration:
  selector: zookeeper
  zookeeper:
    namespace: skywalking
# hostPort missing -> error

# after
configuration:
  selector: zookeeper
  zookeeper:
    hostPort: zk1:2181,zk2:2181
    namespace: skywalking

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

When it happens

Trigger: Selecting configuration-zookeeper as the configuration sync provider (or zookeeper cluster provider sharing these settings) in application.yml while leaving the hostPort key absent, commented out, or set to an empty string. The check runs in initConfigReader() before settings.getHostPort() is ever passed to Curator.

Common situations: Copying a template application.yml and renaming providers without filling in the zookeeper block; YAML indentation mistakes that make the hostPort key parse as part of a different node; relying on environment-variable substitution that resolves to empty.

Related errors

• Zookeeper namespace 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/99e868c5881e123a. Report an issue: GitHub.