What causes "Error updating batch" in pentaho/pentaho-kettle?

Inspect the wrapped KettleDatabaseBatchException's exceptions list to identify the offending rows and fix the data (duplicates, bad values).

pentaho/pentaho-kettle · error · KettleDatabaseBatchException

Error updating batch

Error message

Error updating batch

What it means

When batch mode is enabled, the accumulated JDBC batch of INSERT statements is flushed with PreparedStatement.executeBatch(); a SQLException there is wrapped via Database.createKettleDatabaseBatchException into a 'Error updating batch' exception. It indicates one or more statements in the batch failed at the database.

Solutions

Inspect the wrapped KettleDatabaseBatchException's exceptions list to identify the offending rows and fix the data (duplicates, bad values).
Disable 'Use batch update' in the step, or reduce commit size, to isolate single-row errors.
Verify table constraints and column sizes match the data being inserted.
Check DB connectivity/network stability if failures are intermittent.

Example fix

// before: batch mode on with duplicate PKs in the stream
// after: deduplicate upstream (e.g. 'Unique rows' step) or disable batch update in TableOutput dialog

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight: check for duplicate keys / constraint breakers before insert
Set<String> seen = new HashSet<>();
for ( Object[] row : rows ) {
  String key = buildKey( row );
  if ( !seen.add( key ) ) throw new IllegalArgumentException( "Duplicate key in batch: " + key );
}

Try / catch

try {
  insertStatement.executeBatch();
  data.db.commit();
} catch ( KettleDatabaseBatchException be ) {
  logFailedRows( be.getExceptionsList() );
  data.db.rollback();
  // retry rows individually with batch mode off
}

Prevention

Deduplicate and validate data before TableOutput when using batch mode
Match column sizes/types to table schema to avoid truncation errors
Start with a small commit size and increase once data quality is proven
Monitor connection stability for long-running batch loads

When it happens

Trigger: insertStatement.executeBatch() or data.db.commit() throws SQLException while flushing a batch in writeToTable with data.batchMode active (commit size > 1 and driver supports batch).

Common situations: Constraint violations (PK/unique/FK) on some rows in the batch; data truncation for oversized values; connection dropped mid-batch; deadlock; driver not supporting true batching.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/tableoutput/TableOutput.java:293

      // Release the savepoint if needed
      //
      if ( data.useSafePoints ) {
        if ( data.releaseSavepoint ) {
          data.db.releaseSavepoint( data.savepoint );
        }
      }

      // Perform a commit if needed
      //

      if ( ( data.commitSize > 0 ) && ( ( commitCounter % data.commitSize ) == 0 ) ) {
        if ( data.db.getUseBatchInsert( data.batchMode ) ) {
          try {
            insertStatement.executeBatch();
            data.db.commit();
            insertStatement.clearBatch();
          } catch ( SQLException ex ) {
            throw Database.createKettleDatabaseBatchException( "Error updating batch", ex );
          } catch ( Exception ex ) {
            throw new KettleDatabaseException( "Unexpected error inserting row", ex );
          }
        } else {
          // insertRow normal commit
          data.db.commit();
        }
        // Clear the batch/commit counter...
        //
        data.commitCounterMap.put( tableName, Integer.valueOf( 0 ) );
        rowIsSafe = true;
      } else {
        rowIsSafe = false;
      }

      // See if we need to get back the keys as well...
      if ( meta.isReturningGeneratedKeys() ) {
        RowMetaAndData extraKeys = data.db.getGeneratedKeys( insertStatement );

View on GitHub (pinned to f3058517a1)