pentaho/pentaho-kettle · error · KettleDatabaseException

Couldn't execute SQL:

Error message

Couldn't execute SQL:

What it means

Thrown by Database.execStatement(...) when the JDBC Statement.executeUpdate/execute call raises a SQLException while running arbitrary SQL (DDL or DML). The original SQL text is appended to the message and the SQLException is the cause. It is the standard 'your SQL statement failed on the server' error of the Kettle Database API.

Solutions

  1. Read the wrapped SQLException (getCause()) for the exact server error and fix the SQL accordingly
  2. Verify the table/schema and column names the SQL references actually exist for the connected user
  3. Check the database user's privileges for the statement type (CREATE/ALTER/DROP/INSERT)
  4. Test the exact SQL manually against the target database with the same credentials

Example fix

// before
database.execStatement("INSERT INTO values VALUES(1)");
// after
// 'VALUES' is a reserved word on some databases
database.execStatement("INSERT INTO \"values\" (id) VALUES (1)");
Defensive patterns

Strategy: try-catch

Validate before calling

if (sql == null || sql.trim().isEmpty()) throw new IllegalArgumentException("SQL statement is empty");

Try / catch

try {
  database.execStatement(sql);
} catch (KettleDatabaseException e) {
  Throwable cause = e.getCause();
  if (cause instanceof SQLException) {
    throw new SQLException("execStatement failed for [" + sql + "]: " + cause.getMessage(), cause);
  }
  throw e;
}

Prevention

When it happens

Trigger: Database.execStatement(sql) when the driver returns a SQLException — syntax error, missing table/column, insufficient privileges, or any other server-side rejection of the statement.

Common situations: Generated DDL in transformations failing because the target table already exists or the user lacks CREATE rights; dialect-specific SQL that is invalid on the connected database; typos in SQL script steps; schema not set so the table is not found.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/8048393694ece240. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/database/Database.java:1856

        // You should have called something else!
        if ( count > 0 ) {
          if ( upperSql.startsWith( "INSERT" ) ) {
            result.setNrLinesOutput( count );
          } else if ( upperSql.startsWith( "UPDATE" ) ) {
            result.setNrLinesUpdated( count );
          } else if ( upperSql.startsWith( "DELETE" ) ) {
            result.setNrLinesDeleted( count );
          }
        }
      }

      // See if a cache needs to be cleared...
      if ( upperSql.startsWith( "ALTER TABLE" )
        || upperSql.startsWith( "DROP TABLE" ) || upperSql.startsWith( "CREATE TABLE" ) ) {
        DBCache.getInstance().clear( databaseMeta.getName() );
      }
    } catch ( SQLException ex ) {
      throw new KettleDatabaseException( "Couldn't execute SQL: " + sql + Const.CR, ex );
    } catch ( Exception e ) {
      throw new KettleDatabaseException( "Unexpected error executing SQL: " + Const.CR, e );
    }

    return result;
  }

  /**
   * Execute a series of SQL statements, separated by ;
   * <p/>
   * We are already connected...
   * <p/>
   * Multiple statements have to be split into parts We use the ";" to separate statements...
   * <p/>
   * We keep the results in Result object from Jobs
   *
   * @param script The SQL script to be execute
   * @return A result with counts of the number or records updates, inserted, deleted or read.

View on GitHub (pinned to f3058517a1)