pentaho/pentaho-kettle · error · KettleDatabaseException

Unexpected error executing SQL:

Error message

Unexpected error executing SQL: 

What it means

Also thrown by Database.execStatement(...), but for the generic catch (Exception e) branch: any non-SQLException failure while executing the statement (e.g. NullPointerException, driver class issues, Kettle-internal errors). Note the message intentionally does not include the SQL text.

Solutions

1. Inspect the full stack trace of the cause to find the real runtime failure
2. Ensure connection.open() was called and succeeded before execStatement()
3. Upgrade/align the JDBC driver version with the database server
4. Log the SQL separately since this message does not include it

Example fix

// before
database.execStatement(sql); // connection not opened
// after
database.connect();
database.execStatement(sql);

if (!database.isOpened()) throw new IllegalStateException("Open the connection before execStatement");

try {
  database.execStatement(sql);
} catch (KettleDatabaseException e) {
  // message lacks SQL text — log it yourself
  logError("Unexpected error executing [" + sql + "]", e);
  throw e;
}

When it happens

Trigger: Database.execStatement(sql) when a RuntimeException or other checked exception (not SQLException) is thrown inside the method — e.g. null databaseMeta/connection, driver misbehaving, DBCache errors.

Common situations: Executing SQL before opening the connection; wrong/incomplete JDBC driver version causing unexpected runtime errors; programming bugs in custom DatabaseMeta variants.

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

• An error occurred executing SQL:
• An error occurred executing SQL:
• Couldn't execute SQL:
• Couldn't find any rows because of an error :
• Couldn't get a result because of an error :

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

Appendix: source

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

          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.
   * @throws KettleDatabaseException In case an error occurs
   */

View on GitHub (pinned to f3058517a1)