What causes "GetXMLData.Log.UnableCreateDocument (localized message)" in pentaho/pentaho-kettle?

Validate the failing file with an XML parser (xmllint --noout file.xml) and fix or regenerate it.

pentaho/pentaho-kettle · error · KettleException

GetXMLData.Log.UnableCreateDocument (localized message)

Error message

GetXMLData.Log.UnableCreateDocument (localized message)

What it means

Thrown by ReadNextString when processing a file-based XML source: setDocument(null, file, false, false) returned false, meaning the XML document could not be built/parsed from the file. The step logs the localized 'UnableCreateDocument' message and aborts processing of that row/stream.

Solutions

Validate the failing file with an XML parser (xmllint --noout file.xml) and fix or regenerate it.
Check the step's encoding setting matches the file's actual encoding (set the XML declaration encoding correctly).
Ensure the file is completely written before the transformation picks it up (file-watcher/trigger ordering).
If the file should be skipped, enable error handling on the step instead of letting it abort the transformation.

Example fix

// before
if ( !setDocument( null, file, false, false ) ) {
  throw new KettleException( ... );
}
// after
if ( !isWellFormedXml( file ) ) {
  logError( "Skipping malformed XML file: " + file.getName().getBaseName() );
  return ReadNextString(); // skip bad file
}
if ( !setDocument( null, file, false, false ) ) {
  throw new KettleException( ... );
}

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-validate file before the transformation
Process p = new ProcessBuilder("xmllint", "--noout", xmlPath).start();
if (p.waitFor() != 0) {
  throw new IllegalStateException("Not well-formed XML: " + xmlPath);
}

Try / catch

try {
  trans.execute(null);
} catch (KettleException e) {
  if (e.getMessage().contains("UnableCreateDocument")) {
    logError("Malformed/unreadable XML input; check encoding and file integrity");
  } else { throw e; }
}

Prevention

Validate generated XML files before handing them to PDI.
Match the step encoding setting to the files' real encoding.
Use write-then-rename so only complete files are processed.
Configure step error handling to route bad files aside in production.

When it happens

Trigger: setDocument fails for the current FileObject — typically a parser error from a malformed/non-well-formed XML file, an I/O error reading the file, or an unsupported encoding — during file-based (not field-based) input inside ReadNextString.

Common situations: Input file is truncated, HTML pretending to be XML, or contains invalid characters; file encoding (e.g. UTF-16 file read as UTF-8) misconfigured in the step; file locked or partially written by a producer when the step opens it.

Related errors

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

Appendix: source

Thrown at plugins/xml/core/src/main/java/org/pentaho/di/trans/steps/getxmldata/GetXMLData.java:405

        if ( log.isDetailed() ) {
          logDetailed( BaseMessages.getString( PKG, "GetXMLData.Log.XMLStream", meta.getXMLField(), Fieldvalue ) );
        }

        if ( meta.getIsAFile() ) {
          FileObject file = null;
          try {
            // XML source is a file.
            file = KettleVFS.getInstance( getTransMeta().getBowl() )
              .getFileObject( environmentSubstitute( Fieldvalue ), getTransMeta() );

            if ( meta.isIgnoreEmptyFile() && file.getContent().getSize() == 0 ) {
              logBasic( BaseMessages.getString( PKG, "GetXMLData.Error.FileSizeZero", "" + file.getName() ) );
              return ReadNextString();
            }

            // Open the XML document
            if ( !setDocument( null, file, false, false ) ) {
              throw new KettleException( BaseMessages.getString( PKG, "GetXMLData.Log.UnableCreateDocument" ) );
            }

            if ( !applyXPath() ) {
              throw new KettleException( BaseMessages.getString( PKG, "GetXMLData.Log.UnableApplyXPath" ) );
            }

            addFileToResultFilesname( file );

            if ( log.isDetailed() ) {
              logDetailed( BaseMessages.getString( PKG, "GetXMLData.Log.LoopFileOccurences", "" + data.nodesize, file
                  .getName().getBaseName() ) );
            }

          } catch ( Exception e ) {
            throw new KettleException( e );
          } finally {
            try {
              if ( file != null ) {

View on GitHub (pinned to f3058517a1)