apache/seatunnel · error · TException

Unexpected error creating table: ${dbName}.${tableName}

Error message

Unexpected error creating table: ${dbName}.${tableName}

What it means

A raw org.apache.hadoop.hive.metastore.api.TException thrown by createTableIfNotExists as a defensive catch-all for any unexpected non-Thrift Exception (RuntimeException etc.) during table creation. It signals an unexpected internal failure rather than a metastore-reported error.

Source

Thrown at seatunnel-connectors-v2/connector-hive/src/main/java/org/apache/seatunnel/connectors/seatunnel/hive/utils/HiveMetaStoreCatalog.java:491

    public void createTableIfNotExists(@NonNull Table tbl) throws TException {
        try {
            if (getClient().tableExists(tbl.getDbName(), tbl.getTableName())) {
                log.debug("Table {}.{} already exists", tbl.getDbName(), tbl.getTableName());
                return;
            }
            log.info("Creating table {}.{}", tbl.getDbName(), tbl.getTableName());
            getClient().createTable(tbl);
        } catch (org.apache.hadoop.hive.metastore.api.AlreadyExistsException e) {
            log.debug("Table {}.{} already exists (race)", tbl.getDbName(), tbl.getTableName());
        } catch (TException e) {
            String errorMsg =
                    String.format(
                            "Failed to create table [%s.%s]", tbl.getDbName(), tbl.getTableName());
            throw new HiveConnectorException(
                    HiveConnectorErrorCode.CREATE_HIVE_TABLE_FAILED, errorMsg, e);
        } catch (Exception e) {
            throw new TException(
                    "Unexpected error creating table: "
                            + tbl.getDbName()
                            + "."
                            + tbl.getTableName(),
                    e);
        }
    }

    public void addPartitions(
            @NonNull String dbName, @NonNull String tableName, List<String> partitions)
            throws TException {
        for (String partition : partitions) {
            try {
                getClient().appendPartition(dbName, tableName, partition);
            } catch (AlreadyExistsException ae) {
                log.warn("Partition {} already exists", partition);
            }
        }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the chained cause to find the actual runtime exception.
2. Validate the Table object (dbName, tableName, sd, columns) before calling createTableIfNotExists.
3. Ensure the catalog is open/initialized before use.
4. Capture the full stack trace and file a bug if it persists; this path is not an expected failure mode.

Example fix

// before
// catalog.createTableIfNotExists(tbl); // tbl.getDbName() was null

// after
Objects.requireNonNull(tbl.getDbName(), "dbName required");
Objects.requireNonNull(tbl.getTableName(), "tableName required");
catalog.createTableIfNotExists(tbl);

Objects.requireNonNull(tbl.getDbName(), "dbName");
Objects.requireNonNull(tbl.getTableName(), "tableName");
Objects.requireNonNull(tbl.getSd(), "storage descriptor");

try {
    catalog.createTableIfNotExists(tbl);
} catch (TException e) {
    log.error("Unexpected table create failure for {}.{}: ", tbl.getDbName(), tbl.getTableName(), e.getCause());
    throw e;
}

When it happens

Trigger: Any RuntimeException thrown inside createTableIfNotExists outside the handled TException/AlreadyExistsException branches — e.g. NPE building the Table object, invalid table metadata causing client-side failure.

Common situations: Programmatically constructed Table objects with null dbName/tableName or null storage descriptor; catalog client not initialized; bug in a custom client factory.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• GET_HIVE_TABLE_INFORMATION_FAILED
• Unexpected error creating database: ${db}
• GET_HIVE_TABLE_INFORMATION_FAILED
• Hive metastore_uri is required for regex table discovery (us
• No hive tables matched the regex pattern. Please check `tabl

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