apache/seatunnel · critical · HbaseConnectorException

CONNECTION_FAILED

CONNECTION_FAILED

Error message

Build Hbase connection failed.

What it means

getHbaseConnection() calls ConnectionFactory.createConnection(hbaseConfiguration), which establishes a connection to the HBase cluster. Any IOException (unreachable cluster, ZooKeeper failure, auth error) is wrapped as HbaseConnectorException with CONNECTION_FAILED and message 'Build Hbase connection failed.'.

Solutions

1. Check hbase.zookeeper.quorum, zookeeper port and hbase security settings in the connector config and hbase-site.xml
2. Confirm the HBase cluster is up: telnet/nc to ZooKeeper 2181 and Master/RS ports from the SeaTunnel node
3. Validate Kerberos principal/keytab or user credentials and kinit state
4. Align the hbase-client dependency version with the target HBase cluster version
5. Inspect the wrapped IOException cause for the precise failure (e.g. 'Connection refused', timeout)
6. Add retry around client creation for transient cluster restarts

// precheck connectivity
try (java.net.Socket s = new java.net.Socket(zkHost, 2181)) { /* reachable */ }
System.out.println(org.apache.hadoop.hbase.HBaseConfiguration.create().get("hbase.zookeeper.quorum"));

Connection conn = null;
for (int i = 0; i < 3 && conn == null; i++) {
    try {
        conn = ConnectionFactory.createConnection(hbaseConfiguration);
    } catch (IOException e) {
        if (i == 2) throw new IllegalStateException("Build Hbase connection failed: " + e.getMessage(), e);
        Thread.sleep(2000L * (i + 1));
    }
}

When it happens

Trigger: Any call path that creates an HbaseClient instance (createInstance) when the HBase cluster cannot be reached: bad quorum config, cluster down, Kerberos failure, missing hbase-site.xml.

Common situations: ZooKeeper quorum hostnames wrong or unresolvable from the SeaTunnel worker; HBase cluster restarted/renamed; Kerberos ticket/keytab expired or missing; network/firewall blocking 2181 or 16020; version mismatch between the hbase-client jar and the server.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• CONNECTION_FAILED_FOR_ADMIN
• Client not connected
• CONNECTION_FAILED
• CONNECTION_FAILED
• CREATE_ACTIVEMQ_CLIENT_FAILED

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/0131712d72d6362b. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-connectors-v2/connector-hbase/src/main/java/org/apache/seatunnel/connectors/seatunnel/hbase/client/HbaseClient.java:117

    /**
     * Get Hbase connection.
     *
     * @param hbaseParameters Hbase parameters
     * @return Hbase connection
     */
    private static Connection getHbaseConnection(HbaseParameters hbaseParameters) {
        hbaseConfiguration = HBaseConfiguration.create();
        hbaseConfiguration.set("hbase.zookeeper.quorum", hbaseParameters.getZookeeperQuorum());
        if (hbaseParameters.getHbaseExtraConfig() != null) {
            hbaseParameters.getHbaseExtraConfig().forEach(hbaseConfiguration::set);
        }
        try {
            Connection connection = ConnectionFactory.createConnection(hbaseConfiguration);
            return connection;
        } catch (IOException e) {
            String errorMsg = "Build Hbase connection failed.";
            throw new HbaseConnectorException(
                    HbaseConnectorErrorCode.CONNECTION_FAILED, errorMsg, e);
        }
    }

    /**
     * Check if a database exists.
     *
     * @param databaseName database name
     * @return true if the database exists, false otherwise
     */
    public boolean databaseExists(String databaseName) {
        try {
            return Arrays.stream(admin.listNamespaceDescriptors())
                    .anyMatch(descriptor -> descriptor.getName().equals(databaseName));
        } catch (IOException e) {
            throw new HbaseConnectorException(
                    HbaseConnectorErrorCode.DATABASE_QUERY_EXCEPTION,
                    HbaseConnectorErrorCode.DATABASE_QUERY_EXCEPTION.getErrorMessage(),

View on GitHub (pinned to cf67b549a7)