pentaho/pentaho-kettle · error · KettleException

GPload.Execption.UnhandledLoadMethod

Error message

GPload.Execption.UnhandledLoadMethod

What it means

processRow() dispatches on the configured load method; only 'auto-construct' (load to file then gpload) and 'manual' (build control file only) are supported. Any other value returned by meta.getLoadMethod() throws this KettleException with key GPload.Execption.UnhandledLoadMethod and the offending method value.

Solutions

1. Open the GPLoad step dialog and reselect a valid Load Method (Auto construct or Manual), then save.
2. Inspect the ktr XML for the load method element and correct it to a valid constant.
3. Recreate the step if the metadata is corrupted; verify plugin versions match your Pentaho version.
4. Check for custom or patched GPLoadMeta code that could emit an unsupported method value.

Example fix

// before (ktr xml)
<load_method>custom_method</load_method>
// after
<load_method>auto-construct</load_method>

String method = meta.getLoadMethod();
if (!GPLoadMeta.METHOD_AUTO_CONSTRUCT.equals(method) && !GPLoadMeta.METHOD_MANUAL.equals(method)) {
  throw new IllegalStateException("Unsupported load method in metadata: " + method);
}

boolean isValidLoadMethod(String m) {
  return GPLoadMeta.METHOD_AUTO_CONSTRUCT.equals(m) || GPLoadMeta.METHOD_MANUAL.equals(m);
}

try {
  processRow();
} catch (KettleException ke) {
  if (ke.getMessage().contains("UnhandledLoadMethod")) {
    logError("Fix load_method in the GPLoad step dialog or ktr XML", ke);
  }
  throw ke;
}

When it happens

Trigger: meta.getLoadMethod() returns a string matching neither GPLoadMeta.METHOD_AUTO_CONSTRUCT nor METHOD_MANUAL - normally only possible with corrupted, hand-edited, or version-incompatible step metadata.

Common situations: Hand-edited transformation (ktr) XML; migrating steps across Pentaho versions where method constants changed; third-party tools writing invalid metadata values.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Error while closing output
• Error while executing \'" + commandLine + "\'. Exit value =…
• exceptionMessage
• GPLoad.Exception.DirectoryDoesNotExist
• GPLoad.Exception.GPLoadCommandBuild

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

Appendix: source

Thrown at plugins/gpload/core/src/main/java/org/pentaho/di/trans/steps/gpload/GPLoad.java:609

          if ( GPLoadMeta.METHOD_AUTO_END.equals( loadMethod ) ) {

            // if we actually wrote at least one row
            if ( getLinesOutput() > 0 ) {

              // we do this
              createControlFile( meta );
              execute( meta, true );
            } else {
              // we don't create a control file and execute
              logBasic( BaseMessages.getString( PKG, "GPLoad.Info.NoRowsWritten" ) );
            }
          } else if ( GPLoadMeta.METHOD_MANUAL.equals( loadMethod ) ) {

            // we create the control file but do not execute
            createControlFile( meta );
            logBasic( BaseMessages.getString( PKG, "GPLoad.Info.MethodManual" ) );
          } else {
            throw new KettleException( BaseMessages.getString( PKG, "GPload.Execption.UnhandledLoadMethod", loadMethod ) );
          }
        }
        return false;
      }

      if ( !preview ) {
        if ( first ) {
          first = false;
          output = new GPLoadDataOutput( this, meta, log.getLogLevel() );

          // if ( GPLoadMeta.METHOD_AUTO_CONCURRENT.equals(meta.getLoadMethod()) )
          // {
          // execute(meta, false);
          // }
          output.open( this, gploadProcess );
        }
        output.writeLine( getInputRowMeta(), r );
      }

View on GitHub (pinned to f3058517a1)