apache/seatunnel · error · HbaseConnectorException

TABLE_QUERY_EXCEPTION

TABLE_QUERY_EXCEPTION

Error message

HBase table [%s] does not exist

What it means

This error is thrown by the HBase source split enumerator when the configured table does not exist in the HBase cluster. Before enumerating regions/splits, SeaTunnel calls hbaseClient.tableExists(); if the table is absent it fails fast with TABLE_QUERY_EXCEPTION so the job does not proceed with an empty or invalid source.

Source

Thrown at seatunnel-connectors-v2/connector-hbase/src/main/java/org/apache/seatunnel/connectors/seatunnel/hbase/source/HbaseSourceSplitEnumerator.java:233

                currentTaskSplits.stream()
                        .map(HbaseSourceSplit::splitId)
                        .collect(Collectors.joining(",")));
        context.signalNoMoreSplits(taskId);
    }

    @VisibleForTesting
    public Set<HbaseSourceSplit> getTableSplits() {
        String namespace = hbaseParameters.getNamespace();
        TableName tableName = TableName.valueOf(namespace, hbaseParameters.getTable());
        try {
            HbaseClient hbaseClient = getHbaseClient();
            log.info("Enumerating HBase source splits for table [{}]", tableName.getNameAsString());
            if (!hbaseClient.tableExists(tableName.getNameAsString())) {
                String errorMsg =
                        String.format(
                                "HBase table [%s] does not exist", tableName.getNameAsString());
                log.error(errorMsg);
                throw new HbaseConnectorException(
                        HbaseConnectorErrorCode.TABLE_QUERY_EXCEPTION, errorMsg);
            }

            try (RegionLocator regionLocator =
                    hbaseClient.getRegionLocator(namespace, hbaseParameters.getTable())) {
                byte[][] startKeys = regionLocator.getStartKeys();
                byte[][] endKeys = regionLocator.getEndKeys();
                if (startKeys.length == 0 || endKeys.length == 0) {
                    String errorMsg =
                            String.format(
                                    "No region information found for HBase table [%s], please check whether the table exists "
                                            + "and current user has permission to access it",
                                    tableName.getNameAsString());
                    log.error(errorMsg);
                    throw new HbaseConnectorException(
                            HbaseConnectorErrorCode.TABLE_QUERY_EXCEPTION, errorMsg);
                }
                List<HbaseSourceSplit> splits = new ArrayList<>();

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify the table exists: run 'list' in the HBase shell (or 'exists <table>') on the cluster the job points to.
2. Correct the 'table' (and 'namespace' if set) option in the SeaTunnel source config, including namespace qualification.
3. Confirm the job is connecting to the intended cluster (hbase.zookeeper.quorum / zookeeper.znode.parent match the cluster hosting the table).
4. If the table should exist, check the user's HBase ACLs ('user_permission') since visibility issues can also surface here.
5. Recreate or re-enable the table if it was dropped or disabled before submission.

Example fix

// before
table = "user_events"   // typo, table is 'user_eventsv2'
// after
table = "user_eventsv2"

// HBase shell
exists 'ns:user_events'
// or Java
try (Admin admin = connection.getAdmin()) { admin.tableExists(TableName.valueOf("ns:user_events")); }

try { ... } catch (HbaseConnectorException e) {
  if (e.getErrorCode() == HbaseConnectorErrorCode.TABLE_QUERY_EXCEPTION && e.getMessage().contains("does not exist")) {
    // recreate table or abort with clear config error
  }
}

When it happens

Trigger: Calling splits()/tableSplits() during job startup when hbaseParameters.table (or the namespace-qualified table name) does not exist in the target HBase cluster, e.g. a typo in the table name or the table was dropped before submission.

Common situations: Typo in table name in the HOCON config; job submitted against the wrong cluster/ZK quorum (namespace mismatch); table dropped or renamed between job submission and execution; missing namespace prefix.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Can not find catalog table with factoryId [%s]
• start_timestamp can't be negative
• end_timestamp can't be negative
• start_timestamp must be less than end_timestamp
• startRowkey can't be bigger than endRowkey

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