pentaho/pentaho-kettle · error · SAXException

Invalid Transformation - Missing…

Error message

Invalid Transformation - Missing transformation_configuration tag

What it means

AddTransServlet.validateTransformation throws this SAXException when the uploaded XML payload's root element is not <transformation_configuration>. The servlet rejects the request before parsing the transformation, because the expected configuration envelope tag is missing.

Solutions

  1. Wrap the <transformation> XML inside a <transformation_configuration> root element before uploading.
  2. Check the client/API version — use the envelope format expected by your Pentaho/Carte version.
  3. Verify the first bytes of the POST body actually contain the correct root tag (no BOM/whitespace-prefix issues from a different doctype).
  4. Use a known-good sample request body from the Carte 'Add Trans' documentation as a template.

Example fix

// before: uploading raw transformation XML
InputStream is = new FileInputStream("trans.ktr"); // root: <transformation>
// after: wrap it
String xml = "<transformation_configuration>"
  + new String(Files.readAllBytes(Paths.get("trans.ktr")), StandardCharsets.UTF_8)
  + "</transformation_configuration>";
InputStream is = new ByteArrayInputStream(xml.getBytes(StandardCharsets.UTF_8));
Defensive patterns

Strategy: validation

Validate before calling

String body = new String(Files.readAllBytes(path), StandardCharsets.UTF_8).trim();
if (!body.startsWith("<transformation_configuration")) {
    throw new IllegalArgumentException("Root must be transformation_configuration");
}

Try / catch

try {
    postToAddTrans(xmlBody);
} catch (SAXException e) {
    if (e.getMessage().contains("transformation_configuration")) { /* fix envelope and re-post */ }
    throw e;
}

Prevention

When it happens

Trigger: POSTing to /kettle/addTrans/ with an XML body whose root element is something other than 'transformation_configuration' — e.g. uploading a raw .ktr (root <transformation>) or an execution-info XML instead of the required wrapper.

Common situations: Calling the Carte REST API and uploading transformation.xml directly instead of a transformation_configuration wrapper; using an old client/SDK that predates the transformation_configuration envelope; template copy-paste errors in scripted Carte uploads.

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

Appendix: source

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

  }

  public String getService() {
    return CONTEXT_PATH + " (" + toString() + ")";
  }

  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)