What causes "TransMeta.Exception.InvalidXMLPath" in pentaho/pentaho-kettle?

Verify the file exists at the exact path (File f = new File(fname); f.exists()) before loading

pentaho/pentaho-kettle · error · KettleXMLException

TransMeta.Exception.InvalidXMLPath

Error message

TransMeta.Exception.InvalidXMLPath

What it means

A KettleXMLException (message key TransMeta.Exception.InvalidXMLPath, with fname substituted) thrown by the TransMeta constructor when the resolved VFS FileObject for fname does not exist. The path parsed fine as a URL/URI but no file is actually there.

Solutions

Verify the file exists at the exact path (File f = new File(fname); f.exists()) before loading
Resolve all variables in the path and ensure parentVariableSpace has them set
Use absolute paths or anchor relative paths to a known base directory
Check filename case and extension on case-sensitive filesystems

Example fix

// before
TransMeta tm = new TransMeta(bowl, "${TRANS_HOME}/job.ktr", metaStore, null, true, vars, null);
// after
vars.setVariable("TRANS_HOME", "/opt/etl/trans");
String resolved = vars.realVariableSpace-resolved path; // ensure variables set first
TransMeta tm = new TransMeta(bowl, resolved, metaStore, null, true, vars, null);

Defensive patterns

Strategy: validation

Validate before calling

org.apache.commons.vfs2.FileObject f = KettleVFS.getInstance(bowl).getFileObject(fname, vars);
if (!f.exists()) throw new KettleException("Transformation not found: " + fname);

Try / catch

try { new TransMeta(bowl, fname, ...); } catch (KettleXMLException e) { log.error("Trans file not found at " + fname, e); }

Prevention

Resolve all path variables before loading
Use absolute paths in deployment configs
Check file existence with the same VFS layer Kettle uses

When it happens

Trigger: new TransMeta(bowl, fname, ...) where KettleVFS.getFileObject(fname, parentVariableSpace).exists() returns false — e.g., typo in path, variables in the path unresolved, file deleted.

Common situations: Relative paths evaluated against the wrong working directory; ${Internal...} or custom variables not set in parentVariableSpace; case-sensitive filesystem mismatches; moved/renamed .ktr files.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/TransMeta.java:3078

    this.metaStore = metaStore;
    this.repository = rep;

    // OK, try to load using the VFS stuff...
    Document doc = null;
    try {
      // start by inheriting the bowl from the argument. It might get overwritten later. 
      if ( bowl != null ) {
        setBowl( bowl );
      }
      if ( parentVariableSpace == null ) {
        parentVariableSpace = new Variables();
        // load globals
        parentVariableSpace.initializeVariablesFrom( null );
      }

      final FileObject transFile = KettleVFS.getInstance( bowl ).getFileObject( fname, parentVariableSpace );
      if ( !transFile.exists() ) {
        throw new KettleXMLException( BaseMessages.getString( PKG, "TransMeta.Exception.InvalidXMLPath", fname ) );
      }
      doc = XMLHandler.loadXMLFile( transFile );
    } catch ( KettleXMLException ke ) {
      // if we have a KettleXMLException, simply re-throw it
      throw ke;
    } catch ( KettleException | FileSystemException e ) {
      throw new KettleXMLException( BaseMessages.getString(
        PKG, "TransMeta.Exception.ErrorOpeningOrValidatingTheXMLFile", fname ), e );
    }

    if ( doc != null ) {
      // Root node:
      Node transnode = XMLHandler.getSubNode( doc, XML_TAG );

      if ( transnode == null ) {
        throw new KettleXMLException( BaseMessages.getString(
          PKG, "TransMeta.Exception.NotValidTransformationXML", fname ) );
      }

View on GitHub (pinned to f3058517a1)