pentaho/pentaho-kettle · error · KettleDatabaseException

Unexpected error in combination insert in part [ + debug +…

Error message

Unexpected error in combination insert in part [ + debug + ] :  + e.toString()

What it means

Generic catch-all KettleDatabaseException in combiInsert: any unexpected Exception not caught by the specific prepare/generated-keys handlers is logged with a stack trace and rethrown as 'Unexpected error in combination insert in part [<debug marker>]'. The debug string identifies which phase of combiInsert failed (e.g. 'Create new insert row rins').

Solutions

Read the logged stack trace immediately above the message to find the real exception and the debug phase marker.
Open the step dialog and re-verify all field mappings (key fields, hash field, technical key) so metadata is consistent.
Check the input rows for nulls or unexpected data types in the fields used for hashing/lookup.
If reproducible with specific data, isolate the failing row and fix or filter it upstream.

Example fix

// before: incoming field 'birthdate' sometimes null, causing NPE in hash construction
// after: add a DefaultValue / If Null step upstream
//        (e.g. replace null birthdate with '1900-01-01') before the CombinationLookup.

Defensive patterns

Strategy: try-catch

Validate before calling

// validate input rows upstream: null-check and type-check fields used for hashing
// if (row[i] == null) throw new KettleException("Field " + fieldName + " must not be null");

Try / catch

try { /* run */ } catch (KettleDatabaseException e) {
  // the debug marker and stack trace are logged before this throw — inspect server log
  log.error("combiInsert failed at phase marker logged above; see stack tracker");
}

Prevention

Always read the stack trace logged just before this message to find the real cause.
Normalize nulls and data types before the step (DefaultValue steps).
Re-verify step metadata in the UI instead of editing XML.
Test with representative production data including edge cases.

When it happens

Trigger: Any runtime exception inside combiInsert outside the narrow SQLException handlers — e.g. NullPointerException building the insert row, class cast issues on field values, database meta inconsistencies — escapes to this final catch.

Common situations: Null values or unexpected types in incoming fields; step metadata edited by hand (ktr XML) leaving inconsistent cache/keylookups; bugs triggered by specific data content; memory issues constructing large insert rows.

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

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

Appendix: source

Thrown at plugins/core/impl/src/main/java/org/pentaho/di/trans/steps/combinationlookup/CombinationLookup.java:649

              + meta.getTechnicalKeyField() + ", no fields in resultset" );
          }
        } catch ( SQLException ex ) {
          throw new KettleDatabaseException( "Unable to retrieve auto-increment of combi insert key : "
            + meta.getTechnicalKeyField(), ex );
        } finally {
          try {
            if ( keys != null ) {
              keys.close();
            }
          } catch ( SQLException ex ) {
            throw new KettleDatabaseException( "Unable to retrieve auto-increment of combi insert key : "
              + meta.getTechnicalKeyField(), ex );
          }
        }
      }
    } catch ( Exception e ) {
      logError( Const.getStackTracker( e ) );
      throw new KettleDatabaseException( "Unexpected error in combination insert in part ["
        + debug + "] : " + e.toString(), e );
    }

    return val_key;
  }

  public boolean isRowLevel() {
    return log.isRowLevel();
  }

  public boolean init( StepMetaInterface sii, StepDataInterface sdi ) {
    if ( super.init( sii, sdi ) ) {
      data.realSchemaName = environmentSubstitute( meta.getSchemaName() );
      data.realTableName = environmentSubstitute( meta.getTableName() );

      data.cache = meta.getCacheSize() > 0 ? new HashMap<>( (int) ( meta.getCacheSize() * 1.5 ) ) : new HashMap<>();

      data.db.setCommitSize( meta.getCommitSize() );

View on GitHub (pinned to f3058517a1)