apache/seatunnel · critical · CatalogException

Failed to open catalog %s

Error message

Failed to open catalog %s

What it means

HbaseCatalog.open() wraps any failure while creating the internal HbaseClient instance in a CatalogException with this message. Client creation typically validates HBase connection parameters (quorum, znode, auth) and establishes a connection handle, so configuration or connectivity problems surface here.

Source

Thrown at seatunnel-connectors-v2/connector-hbase/src/main/java/org/apache/seatunnel/connectors/seatunnel/hbase/catalog/HbaseCatalog.java:66

    private final String catalogName;
    private final String defaultDatabase;
    private final HbaseParameters hbaseParameters;

    private HbaseClient hbaseClient;

    public HbaseCatalog(
            String catalogName, String defaultDatabase, HbaseParameters hbaseParameters) {
        this.catalogName = checkNotNull(catalogName, "catalogName cannot be null");
        this.defaultDatabase = defaultDatabase;
        this.hbaseParameters = checkNotNull(hbaseParameters, "Hbase Config cannot be null");
    }

    @Override
    public void open() throws CatalogException {
        try {
            hbaseClient = HbaseClient.createInstance(hbaseParameters);
        } catch (Exception e) {
            throw new CatalogException(String.format("Failed to open catalog %s", catalogName), e);
        }
    }

    @Override
    public void close() throws CatalogException {
        hbaseClient.close();
    }

    @Override
    public String name() {
        return catalogName;
    }

    @Override
    public String getDefaultDatabase() throws CatalogException {
        return defaultDatabase;
    }

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Verify hbase.zookeeper.quorum and hbase.zookeeper.property.clientPort in the connector config match the running HBase cluster.
  2. Check network reachability from the SeaTunnel node to ZooKeeper/HBase (telnet/nc the ports).
  3. Inspect the wrapped cause exception for the root failure (e.g. connection timeout, auth error).
  4. Confirm kerberos/keytab or SASL settings are correct if the cluster is secured.

Example fix

// before
Hbase {
  zookeeper.quorum = "localhost"
}
// after
Hbase {
  zookeeper.quorum = "hbase-host1,hbase-host2,hbase-host3"
  zookeeper.znode.parent = "/hbase"
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Precheck ZooKeeper reachability before opening the catalog
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress(zkQuorumHost, zkPort), 5000); // must succeed
}

Try / catch

try {
    catalog.open();
} catch (CatalogException e) {
    LOG.error("HBase catalog open failed; check quorum/network/security config", e.getCause());
    throw new JobConfigException("Invalid HBase connection settings: " + e.getCause().getMessage());
}

Prevention

When it happens

Trigger: Calling HbaseCatalog.open() when hbaseParameters contain invalid values (bad hbase.zookeeper.quorum, wrong ports) or when ZooKeeper/HBase is unreachable and HbaseClient.createInstance throws.

Common situations: Misconfigured zookeeper quorum host/port; HBase cluster down or firewalled; kerberos/security settings missing or wrong; typo in namespace-related config keys.

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/c31b7c1ea7cf4e5b. Report an issue: GitHub.