pentaho/pentaho-kettle · error · KettleException

PanTransformationDelegate.Error.TransMetaNull

Error message

PanTransformationDelegate.Error.TransMetaNull

What it means

PanTransformationDelegate.executeTransformation throws KettleException when trans.getTransMeta() returns null, meaning the transformation metadata backing the Trans object is missing. This is a defensive check before configuration is applied to the transformation.

Solutions

1. Construct the Trans with a loaded TransMeta: new Trans(new TransMeta(file, repository))
2. Ensure the TransMeta load call succeeded before creating Trans
3. Check that the transformation file path is valid and parseable

Example fix

// before
Trans trans = new Trans();
delegate.executeTransformation(trans, config, args);
// after
TransMeta transMeta = new TransMeta("trans.ktr", repository);
Trans trans = new Trans(transMeta);
delegate.executeTransformation(trans, config, args);

if (trans == null || trans.getTransMeta() == null) {
  throw new IllegalArgumentException("Trans must be constructed with a loaded TransMeta");
}

static boolean hasTransMeta(Trans trans) {
  return trans != null && trans.getTransMeta() != null;
}

try {
  delegate.executeTransformation(trans, config, args);
} catch (KettleException e) {
  if (e.getMessage() != null && e.getMessage().endsWith("TransMetaNull")) {
    throw new IllegalStateException("Pass new Trans(new TransMeta(...)) — TransMeta was null", e);
  }
  throw e;
}

When it happens

Trigger: Calling executeTransformation with a Trans instance constructed without TransMeta, or whose TransMeta was never loaded/assigned.

Common situations: Programmatic use of Pan delegates with a partially built Trans; test harnesses constructing Trans() with the no-arg constructor; failed load path that swallowed a load exception but still returned a Trans.

Related errors

• AnalyseImpactProgressDialog.RuntimeError.UnableToAnalyzeImpact.Exception
• Could not connect to repository: ...
• Error executing transformation and error cleaning up cluster
• GetSQLProgressDialog.RuntimeError.UnableToGenerateSQL.Exception
• MappingInput.Exception.IllegalArgumentSourceStep

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/pan/delegates/PanTransformationDelegate.java:89

    this.transformationExecutorServiceMap = map;
  }

  /**
   * Execute a transformation with the specified configuration.
   *
   * @param trans              the transformation
   * @param executionConfiguration the execution configuration
   * @param arguments              command line arguments
   * @return the execution result
   * @throws KettleException if execution fails
   */
  public Result executeTransformation( final Trans trans,
                                       final TransExecutionConfiguration executionConfiguration,
                                       final String[] arguments ) throws KettleException {

    TransMeta transMeta = trans.getTransMeta();
    if ( transMeta == null ) {
      throw new KettleException( BaseMessages.getString( pkg, "PanTransformationDelegate.Error.TransMetaNull" ) );
    }

    // Set repository and metastore information in both the exec config and the metadata
    transMeta.setRepository( repository );
    transMeta.setMetaStore( MetaStoreConst.getDefaultMetastore() );
    executionConfiguration.setRepository( repository );

    // Set the run options
    transMeta.setClearingLog( executionConfiguration.isClearingLog() );
    transMeta.setSafeModeEnabled( executionConfiguration.isSafeModeEnabled() );
    transMeta.setGatheringMetrics( executionConfiguration.isGatheringMetrics() );

    // Call extension points
    ExtensionPointHandler.callExtensionPoint( log, KettleExtensionPoint.SpoonTransMetaExecutionStart.id, transMeta );
    ExtensionPointHandler.callExtensionPoint( log, KettleExtensionPoint.SpoonTransExecutionConfiguration.id, executionConfiguration );

    try {
      ExtensionPointHandler.callExtensionPoint( log, KettleExtensionPoint.SpoonTransBeforeStart.id, new Object[] {

View on GitHub (pinned to f3058517a1)