pentaho/pentaho-kettle · error · RuntimeException

Unable to load partitioning plugin

Error message

Unable to load partitioning plugin

What it means

StepPartitioningMeta.clone() wraps KettlePluginException in an unchecked RuntimeException when the partitioner plugin cannot be loaded while cloning the step partitioning metadata. This is an internal clone operation, so the failure is almost always a missing or broken partitioner plugin registration.

Solutions

  1. Install/register the partitioner plugin that the step's partitioning method references
  2. Call KettleEnvironment.init() (which initializes the plugin registry) before loading/cloning transformations
  3. Check the cause chain of the RuntimeException for the underlying KettlePluginException
  4. Ensure all cluster slave nodes have the same plugin set as the master

Example fix

// before
KettleVFS.getInstance(); // plugin registry not initialized, clone() fails
// after
KettleEnvironment.init(); // initialize plugin registry first
stepPartitioningMeta = originalStepPartitioningMeta.clone();
Defensive patterns

Strategy: try-catch

Validate before calling

// Before cloning, verify the partitioner plugin loads
KettlePartitioner partitioner = stepPartitioningMeta.getPartitioner();
if (partitioner != null &&
    PluginRegistry.getInstance().getPlugin(
      PartitionerPluginType.class, partitioner.getClass().getName()) == null) {
  throw new IllegalStateException("Partitioner plugin not registered: " + partitioner.getClass());
}

Type guard

boolean partitionerLoadable(StepPartitioningMeta meta) {
  try { if (meta.getPartitioner() != null) meta.getPartitioner().clone(); return true; }
  catch (Exception e) { return false; }
}

Try / catch

try {
  StepPartitioningMeta clone = stepPartitioningMeta.clone();
} catch (RuntimeException e) {
  Throwable cause = e.getCause();
  if (cause instanceof KettlePluginException) {
    log.error("Partitioner plugin missing: " + cause.getMessage());
    // load plugin or abort clone
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling clone() on a StepPartitioningMeta whose method/type requires loading a partitioner plugin (via partitioner.clone() -> KettlePartitioner registry); the plugin fails to load with KettlePluginException and gets rethrown as RuntimeException.

Common situations: Referenced partitioning method (e.g. custom partitioner plugin) not installed on the node cloning the transformation; plugin registry not initialized in embedded/headless usage of Kettle; cluster executions where slave nodes lack the partitioner plugin.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/step/StepPartitioningMeta.java:78

   * @param partitionSchema
   */
  public StepPartitioningMeta( String method, PartitionSchema partitionSchema ) throws KettlePluginException {
    setMethod( method );
    this.partitionSchema = partitionSchema;
    hasChanged = false;
  }

  public StepPartitioningMeta clone() {
    try {
      StepPartitioningMeta stepPartitioningMeta =
        new StepPartitioningMeta( method, partitionSchema != null
          ? (PartitionSchema) partitionSchema.clone() : null );
      stepPartitioningMeta.partitionSchemaName = partitionSchemaName;
      stepPartitioningMeta.setMethodType( methodType );
      stepPartitioningMeta.setPartitioner( partitioner == null ? null : partitioner.clone() );
      return stepPartitioningMeta;
    } catch ( KettlePluginException e ) {
      throw new RuntimeException( "Unable to load partitioning plugin", e );
    }
  }

  /**
   * @return true if the partition schema names are the same.
   */
  @Override
  public boolean equals( Object obj ) {
    if ( obj == null ) {
      return false;
    }
    if ( partitionSchemaName == null ) {
      return false;
    }
    StepPartitioningMeta meta = (StepPartitioningMeta) obj;
    if ( meta.partitionSchemaName == null ) {
      return false;
    }

View on GitHub (pinned to f3058517a1)