pentaho/pentaho-kettle · error · KettleException

Trans.Exception.UnableToOpenTransformation

Error message

Trans.Exception.UnableToOpenTransformation

What it means

The Trans constructor wraps KettleExceptions raised while preparing/opening the transformation and rethrows them as 'UnableToOpenTransformation' with the transformation name, preserving the cause. It indicates the transformation metadata could not be opened/initialized rather than a runtime execution failure.

Solutions

1. Inspect the wrapped cause exception (getCause()) for the real failure
2. Validate the KTR opens in Spoon; re-save or upgrade it if from an older PDI version
3. Check repository connection settings and network availability before constructing Trans

Example fix

// before
Trans t = new Trans(transMeta, rep, "job.ktr", "/dir", "job"); // throws
// after
try {
  Trans t = new Trans(transMeta, rep, "job.ktr", "/dir", "job");
} catch (KettleException e) {
  log.error("Open failed: " + e.getCause(), e); // diagnose the real cause
}

// validate the KTR opens before executing
TransMeta meta = new TransMeta(filename);
if (meta == null || meta.getSteps().isEmpty()) throw new IllegalStateException("Invalid KTR: " + filename);

try { Trans t = new Trans(...); } catch (KettleException e) { log.error("Open failed: " + e.getMessage() + ", cause: " + e.getCause(), e); }

When it happens

Trigger: new Trans(...) construction where an inner KettleException occurs — e.g. failure loading from repository (as in error 1154), invalid file, or errors during setDefaultLogCommitSize/calculateTransactionId setup.

Common situations: Transformation files corrupted or created by an incompatible PDI version; repository connectivity problems; missing named resources/connections referenced by the KTR.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• A deadlock was detected between steps
• AggregateRowsMeta.Exception.UnableToLoadStepInfo
• AppendMeta.Exception.UnableToLoadStepInfo
• At this time we don't support the use of multiple cluster…
• Could not create ValueMetaInterface

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/Trans.java:778

      }

      this.log = new LogChannel( LogChannel.GENERAL_SUBJECT, false, false );
      this.log.setHooks( this );

      transMeta.initializeVariablesFrom( parent );
      initializeVariablesFrom( parent );
      // PDI-3064 do not erase parameters from meta!
      // instead of this - copy parameters to actual transformation
      this.copyParametersFrom( parent );
      this.activateParameters();

      this.setDefaultLogCommitSize();

      // Get a valid transactionId in case we run database transactional.
      transactionId = calculateTransactionId();
      threadName = transactionId; // / backward compatibility but deprecated!
    } catch ( KettleException e ) {
      throw new KettleException( BaseMessages.getString( PKG, "Trans.Exception.UnableToOpenTransformation", name ), e );
    }
  }

  /**
   * Executes the transformation. This method will prepare the transformation for execution and then start all the
   * threads associated with the transformation and its steps.
   *
   * @param arguments the arguments
   * @throws KettleException if the transformation could not be prepared (initialized)
   */
  public void execute( String[] arguments ) throws KettleException {

    // Isolated method call to avoid unnecessary unit tests issues [BACKLOG-36316 / PDI-19357]
    setInitialLogBufferStartLine();
    prepareExecution( arguments );
    startThreads();
  }

View on GitHub (pinned to f3058517a1)