pentaho/pentaho-kettle · error · SAXException

Invalid Transformation Name

Error message

Invalid Transformation Name

What it means

AddTransServlet.validateTransformation throws this SAXException when the /transformation_configuration/transformation/info/name node is missing, has more than one child node, or its first child is not a plain text node. The servlet rejects transformation names that are absent, duplicated, or contain nested markup rather than simple text.

Solutions

  1. Ensure exactly one <info><name> element containing plain text exists under <transformation>.
  2. Escape XML special characters in the transformation name (& → &amp;, < → &lt;).
  3. Remove duplicate <name> nodes — validate the XML structure with an XML parser/linter before POSTing.
  4. Remove any nested elements or comments inside <name>; keep it a simple text value.

Example fix

// before: invalid name content
<info><name>etl &amp; load<env>prod</env></name></info>
// after: single plain-text name
<info><name>etl &amp; load</name></info>
Defensive patterns

Strategy: validation

Validate before calling

DocumentBuilderFactory df = DocumentBuilderFactory.newInstance();
Document doc = df.newDocumentBuilder().parse(new InputSource(new StringReader(xml)));
NodeList names = doc.getElementsByTagName("name");
if (names.getLength() != 1 || names.item(0).getChildNodes().getLength() != 1
    || names.item(0).getFirstChild().getNodeType() != Node.TEXT_NODE) {
    throw new IllegalArgumentException("Exactly one plain-text <name> required");
}

Try / catch

try {
    postToAddTrans(xmlBody);
} catch (SAXException e) {
    if (e.getMessage().equals("Invalid Transformation Name")) { /* fix <info><name> content */ }
    throw e;
}

Prevention

When it happens

Trigger: POSTed XML lacks an <info><name> element under <transformation>, contains multiple/duplicated name nodes, or embeds elements/CDATA/entities inside <name> instead of plain text.

Common situations: Hand-built XML for the Carte addTrans API omitting the info/name element; templating engines injecting extra nodes or escaping into <name>; a transformation name with XML special characters (&, <) that got expanded into nested nodes; copy-paste of config producing duplicate <name> tags.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/www/AddTransServlet.java:356

  public String getContextPath() {
    return CONTEXT_PATH;
  }

  public void validateTransformation( InputStream is ) throws IOException, ParserConfigurationException, SAXException,
    XPathExpressionException {
    DocumentBuilderFactory df = DocumentBuilderFactory.newInstance();
    df.setFeature( "http://xml.org/sax/features/external-general-entities", false );
    df.setFeature( "http://xml.org/sax/features/external-parameter-entities", false );
    DocumentBuilder builder = df.newDocumentBuilder();
    Document doc = builder.parse( is );
    if ( !doc.getDocumentElement().getNodeName().equals( "transformation_configuration" ) ) {
      throw new SAXException( "Invalid Transformation - Missing transformation_configuration tag" );
    }
    XPath xPath = XPathFactory.newInstance().newXPath();
    Node node = (Node) xPath.evaluate( "/transformation_configuration/transformation/info/name", doc, XPathConstants.NODE );
    if ( node == null  || node.getChildNodes().getLength() > 1 || !( node.getFirstChild() instanceof DeferredTextImpl ) ) {
      throw new SAXException( "Invalid Transformation Name" );
    }
  }
}

View on GitHub (pinned to f3058517a1)