apache/seatunnel · error · HbaseConnectorException

TABLE_CREATE_EXCEPTION

TABLE_CREATE_EXCEPTION

Error message

HbaseConnectorErrorCode.TABLE_CREATE_EXCEPTION.getErrorMessage()

What it means

createTable() issues admin.createTable(descriptor) after building the TableDescriptor; any IOException during table creation (including namespace creation inside the try) is wrapped as HbaseConnectorException with TABLE_CREATE_EXCEPTION.

Solutions

Check whether the table was created concurrently and either reuse it (ignoreIfExists) or drop it first
Verify the user has CREATE privileges on the namespace
Validate column families and region/split configuration
Inspect the wrapped IOException cause; confirm HMaster and RegionServer health
Retry after resolving transient cluster problems

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-validate config and existence
if (client.tableExists(TableName.valueOf(ns, table).getNameAsString()) && !ignoreIfExists) {
    throw new IllegalStateException("Table already exists: " + ns + ":" + table);
}
// verify CREATE privilege
try (Connection c = ConnectionFactory.createConnection(conf); Admin a = c.getAdmin()) {
    a.getClusterStatus();
}

Try / catch

try {
    client.createTable(ns, table, families, ignoreIfExists);
} catch (HbaseConnectorException e) {
    if (e.getErrorCode() == HbaseConnectorErrorCode.TABLE_CREATE_EXCEPTION) {
        if (client.tableExists(TableName.valueOf(ns, table).getNameAsString())) {
            log.warn("Table was created concurrently; continuing");
        } else {
            throw e;
        }
    } else throw e;
}

Prevention

Ensure CREATE permission on the namespace for the job user
Avoid concurrent jobs creating the same table; use ignoreIfExists
Validate column families, splits and region config before creating
Check HMaster/RegionServer health before schema changes

When it happens

Trigger: Calling createTable() when admin.createTable fails: table created concurrently by another process, invalid column family/region config, cluster unavailable, or permission denied on create.

Common situations: Two jobs racing to create the same table; HMaster unavailable during job start; user lacks CREATE permission; invalid pre-split keys or region counts; disk issues on RegionServers.

Related errors

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

            TableName table = TableName.valueOf(databaseName, tableName);
            if (tableExists(table.getNameAsString())) {
                log.info("Table {} already exists.", table.getNameAsString());
                if (!ignoreIfExists) {
                    throw new HbaseConnectorException(
                            HbaseConnectorErrorCode.TABLE_EXISTS_EXCEPTION,
                            HbaseConnectorErrorCode.TABLE_EXISTS_EXCEPTION.getErrorMessage());
                }
                return;
            }
            TableDescriptorBuilder hbaseTableDescriptor = TableDescriptorBuilder.newBuilder(table);
            columnFamilies.forEach(
                    family ->
                            hbaseTableDescriptor.setColumnFamily(
                                    ColumnFamilyDescriptorBuilder.newBuilder(Bytes.toBytes(family))
                                            .build()));
            admin.createTable(hbaseTableDescriptor.build());
        } catch (IOException e) {
            throw new HbaseConnectorException(
                    HbaseConnectorErrorCode.TABLE_CREATE_EXCEPTION,
                    HbaseConnectorErrorCode.TABLE_CREATE_EXCEPTION.getErrorMessage(),
                    e);
        }
    }

    /**
     * Drop a table.
     *
     * @param databaseName database name
     * @param tableName table name
     */
    public void dropTable(String databaseName, String tableName) {
        try {
            TableName table = TableName.valueOf(databaseName, tableName);
            admin.disableTable(table);
            admin.deleteTable(table);
        } catch (IOException e) {

View on GitHub (pinned to cf67b549a7)