apache/seatunnel · error · CatalogException

Failed truncate table %s in catalog %s

Error message

Failed truncate table %s in catalog %s

What it means

CatalogException thrown by truncateTableInternal when executing the TRUNCATE TABLE statement fails with any exception. The message names the full table path and catalog; the cause holds the driver-level error.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/catalog/AbstractJdbcCatalog.java:695

    // If sql is DDL, the execute() method always returns false, so the return value
    // should not be used to determine whether changes were made in database.
    protected boolean executeInternal(String url, String sql) throws SQLException {
        LOG.info("Execute sql : {}", sql);
        try (PreparedStatement ps = getConnection(url).prepareStatement(sql)) {
            return ps.execute();
        }
    }

    public CatalogTable getTable(String sqlQuery) throws SQLException {
        Connection defaultConnection = getConnection(defaultUrl);
        return CatalogUtils.getCatalogTable(defaultConnection, sqlQuery);
    }

    protected void truncateTableInternal(TablePath tablePath) throws CatalogException {
        try {
            executeInternal(defaultUrl, getTruncateTableSql(tablePath));
        } catch (Exception e) {
            throw new CatalogException(
                    String.format(
                            "Failed truncate table %s in catalog %s",
                            tablePath.getFullName(), this.catalogName),
                    e);
        }
    }

    protected String getTruncateTableSql(TablePath tablePath) {
        throw new UnsupportedOperationException();
    }

    protected String getExistDataSql(TablePath tablePath) {
        throw new UnsupportedOperationException();
    }

    public void executeSql(TablePath tablePath, String sql) {
        String dbUrl = getUrlFromDatabaseName(tablePath.getDatabaseName());
        Connection connection = getConnection(dbUrl);

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Inspect the wrapped cause for the driver-level reason.
  2. Grant TRUNCATE/ALTER privileges to the catalog user.
  3. Remove or disable foreign keys referencing the table, or use DELETE FROM instead.
  4. Ensure no long-running transactions hold locks on the table.
  5. Verify getTruncateTableSql output against your DBMS syntax manually.

Example fix

// before
catalog.truncateTable(TablePath.of("db", "orders"), false); // FK referenced
// after
try (Connection conn = DriverManager.getConnection(url, user, pass);
     Statement st = conn.createStatement()) {
    st.execute("SET FOREIGN_KEY_CHECKS=0");
    st.execute("TRUNCATE TABLE db.orders");
    st.execute("SET FOREIGN_KEY_CHECKS=1");
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (!catalog.tableExists(tablePath)) return; // nothing to truncate

Try / catch

try { catalog.truncateTable(path, false); } catch (CatalogException e) { LOG.error("Truncate {} failed: {}", path.getFullName(), e.getCause(), e); }

Prevention

When it happens

Trigger: catalog.truncateTable(tablePath, ignoreIfNotExists=false) on an existing table where executeInternal(defaultUrl, getTruncateTableSql(tablePath)) throws: TRUNCATE privilege missing, FK constraints referencing the table, table locked by active transactions, or unsupported truncate syntax.

Common situations: User has DML but not DDL/TRUNCATE rights; MySQL InnoDB table referenced by foreign keys (TRUNCATE fails where DELETE works); row locks from long-running readers/writers; dialect where getTruncateTableSql produces invalid SQL.

Related errors

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