pentaho/pentaho-kettle · error · KettleException

JobTrans.Exception.MetaDataLoad

Error message

JobTrans.Exception.MetaDataLoad

What it means

Thrown from JobEntryTrans's transformation-metadata loading path (getTransMeta-style logic reached from the entry) when loading the referenced transformation's metadata throws a checked KettleException, which is re-thrown unchanged; any other unexpected Exception is wrapped in a KettleException with the JobTrans.Exception.MetaDataLoad message. It means the transformation's .ktr metadata could not be loaded. The root cause is attached.

Solutions

  1. Check the wrapped cause to see whether it's a file, XML, or repository problem
  2. Verify the transformation file/repository path exists and is readable at runtime (resolve any variables)
  3. Re-save/re-export the transformation with a compatible Pentaho version
  4. Confirm repository connection settings and permissions for metadata loading

Example fix

// before
jobEntry.setFilename( "${TRANS_DIR}/etl.ktr" ); // TRANS_DIR unset
// after
String path = jobEntry.environmentSubstitute( "${TRANS_DIR}/etl.ktr" );
if ( !new File( path ).exists() ) throw new IllegalStateException( "Missing ktr: " + path );
jobEntry.setFilename( "${TRANS_DIR}/etl.ktr" );
Defensive patterns

Strategy: validation

Validate before calling

String path = jobEntry.environmentSubstitute( jobEntry.getFilename() );
if ( path != null && !new File( path ).exists() ) {
  throw new IllegalStateException( "Transformation file missing: " + path );
}

Try / catch

try { TransMeta tm = jobEntry.getTransMeta(); } catch ( KettleException e ) { log.error( "Metadata load failed", e.getCause() != null ? e.getCause() : e ); }

Prevention

When it happens

Trigger: The referenced transformation file does not exist or is unreadable, the .ktr XML is corrupt/incompatible, repository-based transformations cannot be found at the given path/id, or repository connection failures occur while loading metadata.

Common situations: Transformation moved/renamed on disk or in the repository after the job was designed; variables used in the transformation path not set at runtime; .ktr saved by a newer Pentaho version; repository permissions preventing metadata reads.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/job/entries/trans/JobEntryTrans.java:1354

        // parent directory (e.g. "/public" instead of "/public/test") when a transformation is invoked
        // from a job entry.

        //  When the child parameter does exist in the parent parameters, overwrite the child parameter by the
        // parent parameter.
        StepWithMappingMeta.replaceVariableValues( transMeta, space, "Trans" );
        if ( isPassingAllParameters() ) {
          // All other parent parameters need to get copied into the child parameters  (when the 'Inherit all
          // variables from the transformation?' option is checked)
          StepWithMappingMeta.addMissingVariables( transMeta, space );
        }
      }

      return transMeta;
    } catch ( final KettleException ke ) {
      // if we get a KettleException, simply re-throw it
      throw ke;
    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString( PKG, "JobTrans.Exception.MetaDataLoad" ), e );
    }
  }

  @Override
  public boolean evaluates() {
    return true;
  }

  @Override
  public boolean isUnconditional() {
    return true;
  }

  @Override
  public List<SQLStatement> getSQLStatements( Repository repository, IMetaStore metaStore, VariableSpace space ) throws KettleException {
    this.copyVariablesFrom( space );
    TransMeta transMeta = getTransMeta( repository, metaStore, this );

View on GitHub (pinned to f3058517a1)