pentaho/pentaho-kettle · error · KettleXMLException

TransMeta.Exception.ErrorOpeningOrValidatingTheXMLFile

Error message

TransMeta.Exception.ErrorOpeningOrValidatingTheXMLFile

What it means

A KettleXMLException (message key TransMeta.Exception.ErrorOpeningOrValidatingTheXMLFile, with fname substituted) thrown when the transformation file exists but XMLHandler.loadXMLFile fails — the file cannot be opened, read, or parsed as XML. The underlying KettleException/FileSystemException is chained as the cause.

Solutions

Check the chained cause (e.getCause()) for the precise parse or IO error
Validate the file with an XML parser (xmllint) to confirm well-formedness
Verify read permissions on the file and that it is a file, not a directory
Re-export or re-save the transformation from Spoon
Confirm file encoding (UTF-8) and remove stray BOMs/binary content

Example fix

// before: loading possibly corrupt file directly
TransMeta tm = new TransMeta(bowl, fname, metaStore, null, true, vars, null);
// after: pre-validate
Document doc = XMLHandler.loadXMLFile(fname); // surface parse errors early with clear message
if (doc == null) throw new KettleException("Not valid XML: " + fname);
TransMeta tm = new TransMeta(bowl, fname, metaStore, null, true, vars, null);

Defensive patterns

Strategy: validation

Validate before calling

Document doc = XMLHandler.loadXMLFile(fname);
if (doc == null) throw new KettleException("File is not well-formed XML: " + fname);

Try / catch

try { new TransMeta(bowl, fname, ...); } catch (KettleXMLException e) { log.error("Could not open/parse trans XML: " + fname + " cause=" + e.getCause(), e); }

Prevention

Pre-validate .ktr files with an XML parser in CI
Guard against truncated file writes/transfer
Verify file permissions and encoding before loading

When it happens

Trigger: new TransMeta(bowl, fname, ...) where the file exists but is unreadable, locked, not valid XML, or has an encoding/BOM problem causing XMLHandler.loadXMLFile(transFile) to throw.

Common situations: Truncated or partially written .ktr files; files with wrong encoding or invalid characters; permission errors on read; the path points to a directory or binary file instead of XML; VFS access issues on network mounts.

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

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

Appendix: source

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

      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 ) );
      }

      // Load from this node...
      loadXML( transnode, fname, metaStore, rep, setInternalVariables, parentVariableSpace, prompter );

    } else {
      throw new KettleXMLException( BaseMessages.getString(
        PKG, "TransMeta.Exception.ErrorOpeningOrValidatingTheXMLFile", fname ) );

View on GitHub (pinned to f3058517a1)