What causes "EXCEPTION: {handler}" in pentaho/pentaho-kettle?

Inspect getCause() for the underlying KettleException and fix that root problem first.

pentaho/pentaho-kettle · error · FunctorException

EXCEPTION

Error message

EXCEPTION: {handler}

What it means

PluginPropertyHandler.Functor.execute wraps any KettleException thrown while handling a PluginProperty into a FunctorException with the message "EXCEPTION: " + this (the functor's toString). It is a generic adapter exception signaling that a property load/save functor failed; the original KettleException is attached as the cause.

Solutions

Inspect getCause() for the underlying KettleException and fix that root problem first.
Ensure the property's XML source is well-formed before running the functor.
Verify output streams/paths are writable when saving properties.
Catch FunctorException around functor execution and handle or log the cause.

Example fix

// before
functor.execute(property);
// after
try {
  functor.execute(property);
} catch (FunctorException e) {
  logger.error("Property handling failed", e.getCause());
}

Defensive patterns

Strategy: try-catch

Validate before calling

if (property == null) {
  throw new IllegalArgumentException("Property must not be null");
}

Try / catch

try {
  functor.execute(property);
} catch (FunctorException e) {
  Throwable root = e.getCause(); // the real KettleException
  log.error("Plugin property handling failed: " + (root != null ? root.getMessage() : e.getMessage()), root);
}

Prevention

Always inspect getCause() — FunctorException only wraps the real error
Validate property XML inputs before running load functors
Ensure output targets are writable before save functors

When it happens

Trigger: Any Functor (e.g. LoadXml, SaveXml, or Fail) whose handle(property) throws a KettleException during execute() — typically XML parsing/writing failures on a plugin property.

Common situations: Loading plugin settings from corrupt or malformed XML; saving properties to an unwritable stream; invoking the Fail sentinel functor in tests.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/core/util/PluginPropertyHandler.java:52

   * @author <a href="mailto:thomas.hoedl@aschauer-edv.at">Thomas Hoedl(asc042)</a>
   *
   */
  public abstract static class AbstractHandler implements Closure {
    /**
     * {@inheritDoc}
     *
     * @see org.apache.commons.collections.Closure#execute(java.lang.Object)
     * @throws IllegalArgumentException
     *           if property is null.
     * @throws FunctorException
     *           if KettleException in handle thrown.
     */
    public final void execute( final Object property ) throws IllegalArgumentException, FunctorException {
      Assert.assertNotNull( property, "Plugin property cannot be null" );
      try {
        this.handle( (PluginProperty) property );
      } catch ( KettleException e ) {
        throw new FunctorException( "EXCEPTION: " + this, e );
      }
    }

    /**
     * Handle property.
     *
     * @param property
     *          property.
     * @throws KettleException
     *           ...
     */
    protected abstract void handle( final PluginProperty property ) throws KettleException;
  }

  /**
   * @author <a href="mailto:thomas.hoedl@aschauer-edv.at">Thomas Hoedl(asc042)</a>
   *
   *         Fail/throws KettleException.

View on GitHub (pinned to f3058517a1)