apache/seatunnel · error · HiveConnectorException

CREATE_HIVE_TABLE_FAILED

CREATE_HIVE_TABLE_FAILED

Error message

Failed to create database [${db}]

What it means

HiveConnectorException (code CREATE_HIVE_TABLE_FAILED) thrown by createDatabaseIfNotExists when the metastore createDatabase call fails with a generic TException. AlreadyExistsException from concurrent creation is tolerated (logged at debug), but any other metastore-side failure is wrapped with the database name.

Source

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

    }

    public void createDatabaseIfNotExists(String db) throws TException {
        try {
            try {
                getClient().getDatabase(db);
                log.debug("Database {} already exists", db);
                return;
            } catch (org.apache.hadoop.hive.metastore.api.NoSuchObjectException ignored) {
            }
            Database database = new Database();
            database.setName(db);
            log.info("Creating database {}", db);
            getClient().createDatabase(database);
        } catch (org.apache.hadoop.hive.metastore.api.AlreadyExistsException e) {
            log.debug("Database {} already exists (race)", db);
        } catch (TException e) {
            String errorMsg = String.format("Failed to create database [%s]", db);
            throw new HiveConnectorException(
                    HiveConnectorErrorCode.CREATE_HIVE_TABLE_FAILED, errorMsg, e);
        } catch (Exception e) {
            throw new TException("Unexpected error creating database: " + db, e);
        }
    }

    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 =

View on GitHub (pinned to cf67b549a7)

Solutions

1. Check the chained TException cause to distinguish permission, name-validation, or connectivity issues.
2. Verify the SeaTunnel process user can write to the Hive warehouse directory on HDFS for the target location.
3. Ensure the database name is a valid Hive identifier (alphanumeric + underscore).
4. Confirm the metastore is reachable and retry; if creation races, rely on the AlreadyExistsException tolerance rather than retry loops.

Example fix

// before: assuming failure means the db is missing
catalog.createDatabaseIfNotExists("etl_db");

// after: check existence first and skip the create when possible
if (!catalog.databaseExists("etl_db")) {
    catalog.createDatabaseIfNotExists("etl_db");
}

if (catalog.databaseExists(db)) return; // skip create

try {
    catalog.createDatabaseIfNotExists(db);
} catch (HiveConnectorException e) {
    if (!catalog.databaseExists(db)) throw e; // real failure, not a benign race
}

When it happens

Trigger: Calling createDatabase -> createDatabaseIfNotExists while the metastore rejects the create: invalid database name, metastore connection error, insufficient HDFS/warehouse permissions for the database location, or transactional conflict other than AlreadyExistsException.

Common situations: Warehouse directory not writable by the SeaTunnel user; invalid characters in db name; metastore briefly unavailable during job start; race with another job creating the same db where the exception type isn't AlreadyExistsException.

Related errors

• Failed to check if database exists: ${dbName}
• GET_HIVE_TABLE_INFORMATION_FAILED
• Unexpected error creating database: ${db}
• Failed to list databases
• Failed to list tables in database: ${databaseName}

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