apache/seatunnel · critical · HbaseConnectorException

CONNECTION_FAILED_FOR_ADMIN

CONNECTION_FAILED_FOR_ADMIN

Error message

CONNECTION_FAILED_FOR_ADMIN

What it means

HbaseClient's constructor builds a BufferedMutator (used for batched writes/admin path) from the HBase connection. If ConnectionFactory/BufferedMutator creation throws an IOException (e.g. cannot reach the cluster, ZooKeeper unavailable, auth failure), the client wraps it as HbaseConnectorException with error code CONNECTION_FAILED_FOR_ADMIN.

Solutions

  1. Verify hbase.zookeeper.quorum/zookeeper.zookeeper.quorum and ports in the SeaTunnel HBase config point to a reachable cluster
  2. Test connectivity to ZooKeeper (2181) and HBase RegionServer/Master ports from the SeaTunnel node
  3. Ensure the configured namespace/table exists or enable auto-creation options before the client builds the mutator
  4. Check Kerberos/credentials (principal, keytab) and that hbase-site.xml is on the classpath
  5. Read the wrapped cause (e) in the exception for the exact connection failure
Defensive patterns

Strategy: try-catch

Validate before calling

// reachability precheck before creating the client
try (java.net.Socket s = new java.net.Socket(quorumHost, 2181)) { /* ok */ }
// plus: ensure namespace/table exists or auto-create is enabled

Try / catch

try {
    client = new HbaseClient(hbaseParameters, hbaseConfiguration);
} catch (HbaseConnectorException e) {
    if (e.getErrorCode() == CONNECTION_FAILED_FOR_ADMIN) {
        log.error("Cannot build HBase buffered mutator: {}", e.getCause(), e);
        throw new RuntimeException("Check hbase.zookeeper.quorum / credentials / table existence", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Constructing HbaseClient when the HBase cluster is unreachable, ZooKeeper quorum is misconfigured (hbase.zookeeper.quorum), the buffered mutator parameters reference a non-existent namespace/table, or Kerberos/credentials fail — resulting in an IOException while creating the BufferedMutator.

Common situations: Wrong hbase.zookeeper.quorum or port in the connector config; HBase master down; firewall or DNS blocking port 2181/16020; namespace or table in the sink config does not exist yet; missing hbase-site.xml on the classpath; Kerberos keytab misconfigured.

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

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/e470394a4e0fe07a. 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:85

     *
     * @param connection Hbase connection
     * @param hbaseParameters Hbase parameters
     */
    private HbaseClient(Connection connection, HbaseParameters hbaseParameters) {
        this.connection = connection;
        try {
            this.admin = connection.getAdmin();

            BufferedMutatorParams bufferedMutatorParams =
                    new BufferedMutatorParams(
                                    TableName.valueOf(
                                            hbaseParameters.getNamespace(),
                                            hbaseParameters.getTable()))
                            .pool(HTable.getDefaultExecutor(hbaseConfiguration))
                            .writeBufferSize(hbaseParameters.getWriteBufferSize());
            hbaseMutator = connection.getBufferedMutator(bufferedMutatorParams);
        } catch (IOException e) {
            throw new HbaseConnectorException(
                    CONNECTION_FAILED_FOR_ADMIN, CONNECTION_FAILED_FOR_ADMIN.getDescription(), e);
        }
    }

    /**
     * Create a new instance of HbaseClient.
     *
     * @param hbaseParameters Hbase parameters
     * @return HbaseClient
     */
    public static HbaseClient createInstance(HbaseParameters hbaseParameters) {
        return new HbaseClient(getHbaseConnection(hbaseParameters), hbaseParameters);
    }

    /**
     * Get Hbase connection.
     *
     * @param hbaseParameters Hbase parameters

View on GitHub (pinned to cf67b549a7)