pentaho/pentaho-kettle · error · KettleDatabaseException

Unexpected error inserting/updating row in part [

Error message

Unexpected error inserting/updating row in part [

What it means

Caught when the same execution path throws a non-SQLException Exception (not SQLException, not BatchUpdateException): wrapped as 'Unexpected error inserting/updating row in part [' + debug + ']'. The debug string names which internal statement part was executing. Since JDBC normally throws SQLException, this usually indicates an infrastructure/runtime problem rather than a SQL error.

Solutions

1. Read the cause stack trace — this is 'unexpected', so the cause is the real story
2. Ensure the insert prepared statement was created (setInsertBatch/prepareInsert) before executing rows
3. Do not share one Database instance across threads without synchronization
4. Reduce batch size to rule out memory pressure
5. Check the 'part [' + debug + ']' label to locate the failing statement part

if (database.getConnection() == null || database.getConnection().isClosed()) {
  throw new IllegalStateException("Cannot insert: connection not open");
}

try {
  database.insertRow(tableName, rowMeta, data);
} catch (KettleDatabaseException e) {
  Throwable c = e.getCause();
  if (c instanceof RuntimeException || c instanceof Error) {
    throw new IllegalStateException("Infrastructure failure in part " + e.getMessage(), c);
  }
  throw e;
}

When it happens

Trigger: Any RuntimeException/Error escaping during executeUpdate — e.g. NullPointerException from unset internal state (null prepared statement), ClassCastException in driver code, KettleRuntimeException, or OutOfMemoryError building large batch payloads.

Common situations: Calling insertRow/executeAndClearBatch before the prepared statement was created; heap exhaustion with very large batches; driver bugs throwing runtime exceptions; concurrent use of a Database object from two threads.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Error inserting/updating row
• A step in transformation [" + transMeta.toString() + "]…
• AccessInputMeta.Exception.ErrorSavingToRepository
• An error occurred executing SQL:
• An error occurred executing SQL:

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

Appendix: source

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

        } else {
          debug = "insertRow normal commit";
          commit();
        }
        written = 0;
        rowsAreSafe = true;
      }

      return rowsAreSafe;
    } catch ( BatchUpdateException ex ) {
      throw createKettleDatabaseBatchException( "Error updating batch", ex );
    } catch ( SQLException ex ) {
      if ( isBatchUpdate ) {
        throw createKettleDatabaseBatchException( "Error updating batch", ex );
      } else {
        throw new KettleDatabaseException( "Error inserting/updating row", ex );
      }
    } catch ( Exception e ) {
      throw new KettleDatabaseException( "Unexpected error inserting/updating row in part [" + debug + "]", e );
    }
  }

  /**
   * Clears batch of insert prepared statement
   *
   * @throws KettleDatabaseException
   * @deprecated
   */
  @Deprecated
  public void clearInsertBatch() throws KettleDatabaseException {
    clearBatch( prepStatementInsert );
  }

  public void clearBatch( PreparedStatement preparedStatement ) throws KettleDatabaseException {
    try {
      preparedStatement.clearBatch();
    } catch ( SQLException e ) {

View on GitHub (pinned to f3058517a1)