pentaho/pentaho-kettle · error · KettleException

There was an unexpected error:

Error message

There was an unexpected error:

What it means

TransExecutor.processRow() catches any exception during execution of the sub-transformation (initialization, row injection, or result collection) and rethrows it as a KettleException with the localized 'TransExecutor.UnexpectedError' message ('There was an unexpected error:'). The real cause is the chained exception.

Solutions

1. Log/print the full stack trace of the chained cause — it names the actual failure.
2. Verify the sub-transformation path/filename resolves and runs standalone in Spoon.
3. Check that all sub-transformation parameters/mapping of input fields are correctly configured.
4. Increase logging on the executor step and re-run to pinpoint the failing inner step.

// Before executing, verify the sub-transformation file exists and parameters map
File subTrans = new File(environmentSubstitute(transExecutorMeta.getFileName()));
if (!subTrans.exists()) throw new IllegalStateException("Sub-transformation missing: " + subTrans);

try { trans.execute(new String[0]); }
catch (KettleException e) {
  Throwable root = e; while (root.getCause() != null) root = root.getCause();
  log.error("TransExecutor failed, root cause: {}", root.toString(), e);
}

When it happens

Trigger: Any failure inside processRow's try block: initOnFirstProcessingIteration errors, prepareExecution of the executor sub-transformation failing, putRow into the sub-transformation failing, or result retrieval problems while the step runs.

Common situations: The configured sub-transformation fails to start (missing file, bad parameters); sub-transformation steps error at runtime; group-field misconfiguration; memory exhaustion running many sub-transformations.

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

• All input files need to have the same number of fields. File
• AutoDoc.Exception.FilenameFieldNotFound
• AutoDoc.Exception.FileTypeFieldNotFound
• AutoDoc.Exception.UnableToDetermineLocation
• AutoDoc.Exception.UnableToRenderReport

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/transexecutor/TransExecutor.java:140

          }
        }
      }

      // Add next value AFTER transformation execution, in case we are grouping by field (see PDI-14958),
      // and BEFORE checking size of a group, in case we are grouping by size (see PDI-14121).
      transExecutorData.groupBuffer.add( new RowMetaAndData( getInputRowMeta(), row ) ); // should we clone for safety?

      // Grouping by size.
      // If group buffer size exceeds specified limit, then execute transformation and flush group buffer.
      if ( transExecutorData.groupSize > 0 ) {
        if ( transExecutorData.groupBuffer.size() >= transExecutorData.groupSize ) {
          executeTransformation( incomingFieldValues );
        }
      }

      return true;
    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString( PKG, "TransExecutor.UnexpectedError" ), e );
    }
  }

  private void initOnFirstProcessingIteration() throws KettleException {
    TransExecutorData transExecutorData = getData();
    // internal transformation's first step has exactly the same input
    transExecutorData.setInputRowMeta( getInputRowMeta() );

    // internal transformation's execution results
    transExecutorData.setExecutionResultsOutputRowMeta( new RowMeta() );
    if ( meta.getExecutionResultTargetStepMeta() != null ) {
      meta.prepareExecutionResultsFields( transExecutorData.getExecutionResultsOutputRowMeta(),
        meta.getExecutionResultTargetStepMeta() );
      transExecutorData
        .setExecutionResultRowSet( findOutputRowSet( meta.getExecutionResultTargetStepMeta().getName() ) );
    }
    // internal transformation's execution result's file
    transExecutorData.setResultFilesOutputRowMeta( new RowMeta() );

View on GitHub (pinned to f3058517a1)