{"record":{"id":"0131712d72d6362b","repo":"apache/seatunnel","slug":"connection-failed-013171","errorCode":"CONNECTION_FAILED","errorMessage":"Build Hbase connection failed.","messagePattern":"Build Hbase connection failed\\.","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":117,"sourceCode":"\n    /**\n     * Get Hbase connection.\n     *\n     * @param hbaseParameters Hbase parameters\n     * @return Hbase connection\n     */\n    private static Connection getHbaseConnection(HbaseParameters hbaseParameters) {\n        hbaseConfiguration = HBaseConfiguration.create();\n        hbaseConfiguration.set(\"hbase.zookeeper.quorum\", hbaseParameters.getZookeeperQuorum());\n        if (hbaseParameters.getHbaseExtraConfig() != null) {\n            hbaseParameters.getHbaseExtraConfig().forEach(hbaseConfiguration::set);\n        }\n        try {\n            Connection connection = ConnectionFactory.createConnection(hbaseConfiguration);\n            return connection;\n        } catch (IOException e) {\n            String errorMsg = \"Build Hbase connection failed.\";\n            throw new HbaseConnectorException(\n                    HbaseConnectorErrorCode.CONNECTION_FAILED, errorMsg, e);\n        }\n    }\n\n    /**\n     * Check if a database exists.\n     *\n     * @param databaseName database name\n     * @return true if the database exists, false otherwise\n     */\n    public boolean databaseExists(String databaseName) {\n        try {\n            return Arrays.stream(admin.listNamespaceDescriptors())\n                    .anyMatch(descriptor -> descriptor.getName().equals(databaseName));\n        } catch (IOException e) {\n            throw new HbaseConnectorException(\n                    HbaseConnectorErrorCode.DATABASE_QUERY_EXCEPTION,\n                    HbaseConnectorErrorCode.DATABASE_QUERY_EXCEPTION.getErrorMessage(),","sourceCodeStart":99,"sourceCodeEnd":135,"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#L99-L135","documentation":"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.'.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check hbase.zookeeper.quorum, zookeeper port and hbase security settings in the connector config and hbase-site.xml","Confirm the HBase cluster is up: telnet/nc to ZooKeeper 2181 and Master/RS ports from the SeaTunnel node","Validate Kerberos principal/keytab or user credentials and kinit state","Align the hbase-client dependency version with the target HBase cluster version","Inspect the wrapped IOException cause for the precise failure (e.g. 'Connection refused', timeout)","Add retry around client creation for transient cluster restarts"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// precheck connectivity\ntry (java.net.Socket s = new java.net.Socket(zkHost, 2181)) { /* reachable */ }\nSystem.out.println(org.apache.hadoop.hbase.HBaseConfiguration.create().get(\"hbase.zookeeper.quorum\"));","typeGuard":null,"tryCatchPattern":"Connection conn = null;\nfor (int i = 0; i < 3 && conn == null; i++) {\n    try {\n        conn = ConnectionFactory.createConnection(hbaseConfiguration);\n    } catch (IOException e) {\n        if (i == 2) throw new IllegalStateException(\"Build Hbase connection failed: \" + e.getMessage(), e);\n        Thread.sleep(2000L * (i + 1));\n    }\n}","preventionTips":["Verify hbase.zookeeper.quorum resolves from all worker nodes","kinit / refresh Kerberos keytabs before long-running jobs","Monitor HBase master health before job submission","Pin hbase-client version to match the server 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"}