{"record":{"id":"e470394a4e0fe07a","repo":"apache/seatunnel","slug":"connection-failed-for-admin","errorCode":"CONNECTION_FAILED_FOR_ADMIN","errorMessage":"CONNECTION_FAILED_FOR_ADMIN","messagePattern":"CONNECTION_FAILED_FOR_ADMIN","errorType":"error_code","errorClass":"HbaseConnectorException","httpStatus":null,"severity":"critical","filePath":"seatunnel-connectors-v2/connector-hbase/src/main/java/org/apache/seatunnel/connectors/seatunnel/hbase/client/HbaseClient.java","lineNumber":85,"sourceCode":"     *\n     * @param connection Hbase connection\n     * @param hbaseParameters Hbase parameters\n     */\n    private HbaseClient(Connection connection, HbaseParameters hbaseParameters) {\n        this.connection = connection;\n        try {\n            this.admin = connection.getAdmin();\n\n            BufferedMutatorParams bufferedMutatorParams =\n                    new BufferedMutatorParams(\n                                    TableName.valueOf(\n                                            hbaseParameters.getNamespace(),\n                                            hbaseParameters.getTable()))\n                            .pool(HTable.getDefaultExecutor(hbaseConfiguration))\n                            .writeBufferSize(hbaseParameters.getWriteBufferSize());\n            hbaseMutator = connection.getBufferedMutator(bufferedMutatorParams);\n        } catch (IOException e) {\n            throw new HbaseConnectorException(\n                    CONNECTION_FAILED_FOR_ADMIN, CONNECTION_FAILED_FOR_ADMIN.getDescription(), e);\n        }\n    }\n\n    /**\n     * Create a new instance of HbaseClient.\n     *\n     * @param hbaseParameters Hbase parameters\n     * @return HbaseClient\n     */\n    public static HbaseClient createInstance(HbaseParameters hbaseParameters) {\n        return new HbaseClient(getHbaseConnection(hbaseParameters), hbaseParameters);\n    }\n\n    /**\n     * Get Hbase connection.\n     *\n     * @param hbaseParameters Hbase parameters","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-hbase/src/main/java/org/apache/seatunnel/connectors/seatunnel/hbase/client/HbaseClient.java#L67-L103","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify hbase.zookeeper.quorum/zookeeper.zookeeper.quorum and ports in the SeaTunnel HBase config point to a reachable cluster","Test connectivity to ZooKeeper (2181) and HBase RegionServer/Master ports from the SeaTunnel node","Ensure the configured namespace/table exists or enable auto-creation options before the client builds the mutator","Check Kerberos/credentials (principal, keytab) and that hbase-site.xml is on the classpath","Read the wrapped cause (e) in the exception for the exact connection failure"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// reachability precheck before creating the client\ntry (java.net.Socket s = new java.net.Socket(quorumHost, 2181)) { /* ok */ }\n// plus: ensure namespace/table exists or auto-create is enabled","typeGuard":null,"tryCatchPattern":"try {\n    client = new HbaseClient(hbaseParameters, hbaseConfiguration);\n} catch (HbaseConnectorException e) {\n    if (e.getErrorCode() == CONNECTION_FAILED_FOR_ADMIN) {\n        log.error(\"Cannot build HBase buffered mutator: {}\", e.getCause(), e);\n        throw new RuntimeException(\"Check hbase.zookeeper.quorum / credentials / table existence\", e);\n    }\n    throw e;\n}","preventionTips":["Validate quorum host/port connectivity from SeaTunnel worker nodes before submitting jobs","Ensure hbase-site.xml/kerberos config is on the classpath and credentials are fresh","Create the namespace/table (or enable auto-create) before the sink starts","Keep hbase-client dependency version aligned with the cluster"],"tags":["hbase","connection","zookeeper","network"],"backgroundTag":"connection-refused","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}