pentaho/pentaho-kettle · error · KettleException

process stderr/stdout output on non-zero exit status

Error message

process stderr/stdout output on non-zero exit status

What it means

With 'fail when not success' enabled, a non-zero exit code from the spawned process makes ExecProcess throw with the process's stderr (or stdout if stderr is empty) as the message. The step surfaces the child process's own output as the Kettle error.

Solutions

  1. Read the exception message (the process's stderr/stdout) to see why the command failed.
  2. Verify the command and arguments for that specific row are correct (log processString and argument fields).
  3. Uncheck 'Fail when not success' if non-zero exits are acceptable, and inspect the result field instead.
  4. Fix the external command/environment (PATH, permissions, script bugs).

Example fix

// before: step configured to fail on any non-zero exit
meta.setFailWhenNotSuccess(true);
// after: tolerate and inspect exit status via the result field
meta.setFailWhenNotSuccess(false);
// then branch on the exit-status/result field downstream
Defensive patterns

Strategy: try-catch

Validate before calling

// test the command manually with the same arguments first
// e.g. /opt/scripts/myscript.sh arg1 arg2 ; echo $?

Try / catch

try { rowListener/processRow output } catch (KettleException e) { log.error("Process failed: " + e.getMessage()); /* message is the child's stderr/stdout */ }

Prevention

When it happens

Trigger: processRow, per row: processResult.getExistStatus() != 0 and meta.isFailWhenNotSuccess() is true — e.g. the command is missing (exit 127), has bad arguments (exit 1-2), or returns failure for that row's input.

Common situations: Command path not on PATH; wrong arguments built from row fields; script exits non-zero for expected conditions (file not found); Windows vs Unix shell differences; permissions on the executable.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/execprocess/ExecProcess.java:148

        for ( int i = 0; i < data.indexOfArguments.length; i++ ) {
          // Runtime.exec will fail on null array elements
          // Convert to an empty string if value is null
          String argString = data.previousRowMeta.getString( r, data.indexOfArguments[i] );
          cmdArray.add( Const.NVL( argString, "" ) );
        }

        execProcess( cmdArray.toArray( new String[0] ), processResult );
      } else {
        execProcess( processString, processResult );
      }

      if ( meta.isFailWhenNotSuccess() ) {
        if ( processResult.getExistStatus() != 0 ) {
          String errorString = processResult.getErrorStream();
          if ( Utils.isEmpty( errorString ) ) {
            errorString = processResult.getOutputStream();
          }
          throw new KettleException( errorString );
        }
      }

      // Add result field to input stream
      int rowIndex = data.NrPrevFields;
      outputRow[rowIndex++] = processResult.getOutputStream();

      // Add result field to input stream
      outputRow[rowIndex++] = processResult.getErrorStream();

      // Add result field to input stream
      outputRow[rowIndex++] = processResult.getExistStatus();

      // add new values to the row.
      putRow( data.outputRowMeta, outputRow ); // copy row to output rowset(s);

      if ( log.isRowLevel() ) {
        logRowlevel( BaseMessages.getString( PKG, "ExecProcess.LineNumber", getLinesRead()

View on GitHub (pinned to f3058517a1)