pentaho/pentaho-kettle · error · KettleXMLException

TransMeta.Exception.NotValidTransformationXML

Error message

TransMeta.Exception.NotValidTransformationXML

What it means

TransMeta(String fname, ...) loads a transformation from an XML file. After parsing, it looks for the root <transformation> element via XMLHandler.getSubNode(doc, XML_TAG). If that element is missing, KettleXMLException with TransMeta.Exception.NotValidTransformationXML is thrown because the file, although well-formed XML, is not a Pentaho/Kettle transformation definition.

Solutions

  1. Verify the file is a transformation (.ktr) whose root element is <transformation>, not a job (.kjb) or other XML
  2. Open the file in Spoon or inspect the first lines to confirm the root tag
  3. Regenerate/export the transformation from Pentaho if it is corrupted or truncated

Example fix

// before
TransMeta tm = new TransMeta("job.kjb"); // throws NotValidTransformationXML
// after
TransMeta tm = new TransMeta("transformation.ktr"); // root: <transformation>
Defensive patterns

Strategy: validation

Validate before calling

boolean isTransformationXml(String path) throws Exception {
  DocumentBuilderFactory f = DocumentBuilderFactory.newInstance();
  Document doc = f.newDocumentBuilder().parse(new File(path));
  return doc.getDocumentElement().getTagName().equals("transformation");
}
if (!isTransformationXml(fname)) throw new IllegalArgumentException(fname + " is not a .ktr transformation");

Type guard

if (doc == null || !"transformation".equals(doc.getDocumentElement().getTagName())) return false;

Try / catch

try {
  TransMeta tm = new TransMeta(fname);
} catch (KettleXMLException e) {
  logger.error("Not a valid transformation XML: {}", fname, e);
  throw new IllegalArgumentException("Expected a .ktr transformation file", e);
}

Prevention

When it happens

Trigger: Calling new TransMeta(fname) (or TransMeta.fromXML/TransMeta(...)) on an XML file whose root tag is not 'transformation' (e.g. a job .kjb file, a saved UI layout, arbitrary XML).

Common situations: Passing a .kjb job file where a .ktr transformation is expected; file renamed/corrupted; wrong file handed to the transformation loader; exporting the wrong artifact type.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

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

  /**
   * Instantiates a new transformation meta-data object.
   *
   * @param xmlStream
   *          the XML input stream from which to read the transformation definition
   * @param fname

View on GitHub (pinned to f3058517a1)