What causes "ExecuteTransServlet.Error.ErrorExecutingTrans" in pentaho/pentaho-kettle?

Read the transformation log in the exception message/cause to find the failing step

pentaho/pentaho-kettle · error · KettleException

ExecuteTransServlet.Error.ErrorExecutingTrans

ExecuteTransServlet.Error.ErrorExecutingTrans

Error message

ExecuteTransServlet.Error.ErrorExecutingTrans

What it means

KettleException thrown by ExecuteTransServlet.doGet when the transformation execution fails; the transformation's log buffer is attached as the message and the original exception as the cause. It wraps any error during trans execution (steps failing, resource errors, runtime exceptions) so the HTTP caller receives a single descriptive failure.

Solutions

Read the transformation log in the exception message/cause to find the failing step
Fix the underlying transformation error (connection, file path, parameter values)
Ensure required variables and parameters are passed in the request or set on the server
Check the Carte server logs and memory availability
Test the transformation locally in Spoon with the same runtime parameters

Example fix

// before
// client ignores cause details
} catch ( KettleException e ) { LOG.error("trans failed"); }
// after
} catch ( KettleException e ) {
  LOG.error( "Transformation failed: " + e.getMessage(), e.getCause() ); // cause holds the step-level error
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate before execution: parameters present and connection-able resources
for ( String var : requiredVars ) {
  if ( transMeta.getParameterValue( var ) == null && System.getProperty( var ) == null ) {
    throw new IllegalStateException( "Missing parameter: " + var );
  }
}

Try / catch

try {
  // executeTrans call
} catch ( KettleException e ) {
  // message contains the transformation log buffer; persist it for diagnosis
  LOG.error( "Trans execution failed:\n" + e.getMessage(), e );
}

Prevention

Pass all required variables/parameters in the request
Pre-test transformations in Spoon with production-like inputs
Monitor Carte server memory for OOM-driven execution failures
Keep step plugins installed and version-matched on the server

When it happens

Trigger: GET /kettle/executeTrans/ authenticates and prepares the TransMeta successfully, but trans.execute()/waitUntilFinished() throws or the execution exception path is reached — logged content is captured via KettleLogStore.getAppender().getBuffer(trans.getLogChannelId()).

Common situations: Transformation step errors (DB connection failures, missing files/tables); variables/parameters unresolved at runtime; OOM or resource limits on the Carte server; plugin/step class missing at runtime.

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/fe7633740f6347a2. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/www/ExecuteTransServlet.java:332

      //
      trans.setServletPrintWriter( out );
      trans.setServletReponse( response );
      trans.setServletRequest( request );

      try {
        // Execute the transformation...
        //
        executeTrans( trans );
        String logging = KettleLogStore.getAppender().getBuffer( trans.getLogChannelId(), false ).toString();
        if ( trans.isFinishedOrStopped() && trans.getErrors() > 0 ) {
          response.setStatus( HttpServletResponse.SC_INTERNAL_SERVER_ERROR );
          out.println( new WebResult( WebResult.STRING_ERROR, BaseMessages.getString(
            PKG, "ExecuteTransServlet.Error.ErrorExecutingTrans", logging ) ) );
        }
        out.flush();
      } catch ( Exception executionException ) {
        String logging = KettleLogStore.getAppender().getBuffer( trans.getLogChannelId(), false ).toString();
        throw new KettleException( BaseMessages.getString( PKG, "ExecuteTransServlet.Error.ErrorExecutingTrans", logging ), executionException );
      }
    } catch ( Exception ex ) {
      // When we get to this point KettleAuthenticationException has already been wrapped in an Execution Exception
      // and that in a KettleException
      Throwable kettleExceptionCause = ex.getCause();
      if ( kettleExceptionCause != null && kettleExceptionCause instanceof ExecutionException ) {
        Throwable executionExceptionCause = kettleExceptionCause.getCause();
        if ( executionExceptionCause != null && executionExceptionCause instanceof KettleAuthenticationException ) {
          response.setStatus( HttpServletResponse.SC_UNAUTHORIZED );
          out.println( new WebResult( WebResult.STRING_ERROR, BaseMessages.getString(
                  PKG, "ExecuteTransServlet.Error.Authentication", getContextPath() ) ) );
        }
      } else if ( ex.getMessage().contains( UNABLE_TO_FIND_TRANS ) ) {
        response.setStatus( HttpServletResponse.SC_NOT_FOUND );
        out.println( new WebResult( WebResult.STRING_ERROR, BaseMessages.getString(
                PKG, "ExecuteTransServlet.Error.UnableToFindTransformation", transOption ) ) );
      } else {
        response.setStatus( HttpServletResponse.SC_INTERNAL_SERVER_ERROR );

View on GitHub (pinned to f3058517a1)