When configuring HBase to use an external ZooKeeper ensemble, you might encounter this frustrating port conflict even after setting HBASE_MANAGES_ZK=false. The root cause typically stems from residual configurations or improper service startup sequences.

First, verify these critical settings in your hbase-site.xml:

  hbase.cluster.distributed
  true


  hbase.zookeeper.property.clientPort
  2181


  hbase.zookeeper.quorum
  zk1.example.com,zk2.example.com,zk3.example.com

Before starting HBase, ensure your external ZooKeeper is properly running:

# Verify ZooKeeper status
echo stat | nc localhost 2181 | grep Mode

# Check listening ports
netstat -tnlp | grep 2181

1. Conflicting Service Definitions: Some distributions bundle ZooKeeper startup scripts in HBase's init.d files. Check for:

grep -r "zookeeper" /etc/init.d/hbase-*

2. Multiple Configuration Overrides: HBase may load configurations from multiple locations. Use this command to verify active settings:

hbase shell <<EOF
  get 'hbase:meta', 'config:'
  exit
EOF

Enable detailed logging by adding these to hbase-env.sh:

export HBASE_OPTS="$HBASE_OPTS -Dorg.apache.zookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty -Dzookeeper.clientCnxnSocket=true"
export HBASE_ROOT_LOGGER=DEBUG,console

Examine the complete startup sequence:

tail -f $HBASE_HOME/logs/hbase-*-master-*.log | grep -i zookeeper

For complex environments, consider specifying ZooKeeper properties directly:

  hbase.zookeeper.property.dataDir
  /var/lib/zookeeper


  hbase.zookeeper.property.maxClientCnxns
  500

After making changes, verify the configuration through HBase Shell:

hbase(main):001:0> status 'detailed'
hbase(main):002:0> config 'hbase.zookeeper.quorum'

---

The error message indicates HBase is still attempting to start its internal ZooKeeper despite setting HBASE_MANAGES_ZK=false. This typically occurs when:

2023-08-15 12:34:56 ERROR [main] zookeeper.ZooKeeperServer: Could not start ZK at requested port of 2181
2023-08-15 12:34:56 WARN [main] hbase.ZooKeeperConnectionException: ZK was started at port: 2182

Verify these critical configurations in hbase-site.xml:

<configuration>
  <property>
    <name>hbase.cluster.distributed</name>
    <value>true</value>
  </property>
  <property>
    <name>hbase.zookeeper.quorum</name>
    <value>localhost</value>
  </property>
  <property>
    <name>hbase.zookeeper.property.clientPort</name>
    <value>2181</value>
  </property>
</configuration>

Run this diagnostic command before starting HBase:

netstat -tulnp | grep 2181
ps aux | grep -i zookeeper

Common findings that trigger this issue:

• ZooKeeper process running under different user
• Multiple ZooKeeper instances in process list
• SELinux/iptables blocking port access

1. First stop all running instances:

# Stop HBase first
./bin/stop-hbase.sh

# Stop ZooKeeper explicitly
./bin/zkServer.sh stop

2. Clean up temporary files:

rm -rf /tmp/hbase-*
rm -rf /tmp/zookeeper/*

3. Verify environment variables:

export HBASE_MANAGES_ZK=false
export ZOOKEEPER_HOME=/path/to/zookeeper

4. Start services in correct order:

# Start ZooKeeper first
$ZOOKEEPER_HOME/bin/zkServer.sh start

# Then start HBase
./bin/start-hbase.sh

If the issue persists, examine these log files:

tail -n 100 $HBASE_HOME/logs/hbase-*-master-*.log
grep -i "zookeeper" $HBASE_HOME/logs/hbase-*-regionerver-*.log

Common advanced fixes include:

• Setting export SERVER_JVMFLAGS="-Dzookeeper.admin.enableServer=false"
• Modifying zoo.cfg to explicitly set admin.serverPort=8080
• Adjusting JVM parameters in hbase-env.sh