pentaho/pentaho-kettle · error · DocumentBuilderInitializationException

Failed to initialize default DocumentBuilder for XML parsing

Error message

Failed to initialize default DocumentBuilder for XML parsing

What it means

XMLHandler's static ThreadLocal DEFAULT_BUILDER_CACHE initializes a default DocumentBuilder via createDocumentBuilder(false, true); if that fails with a KettleXMLException, it is rethrown as a DocumentBuilderInitializationException with this message, wrapping the cause. This means the JVM could not create a namespace-unaware, validating-secure default parser (typically a ParserConfigurationException).

Solutions

  1. Read the wrapped cause (getCause()) — the KettleXMLException/ParserConfigurationException names the real factory failure
  2. Check/unset javax.xml.parsers.DocumentBuilderFactory system properties that override the default JAXP factory
  3. Remove conflicting XML parser JARs from the classpath (xerces/rt conflicts, shaded duplicates)
  4. Ensure the parser classes are visible to the thread's classloader (correct plugin/lib packaging)
  5. Catch the exception on first parse and fall back to an explicitly created DocumentBuilder

Example fix

// before
Document doc = XMLHandler.loadXMLString( xml ); // may blow up in cache init
// after
try {
  Document doc = XMLHandler.loadXMLString( xml );
} catch ( Throwable t ) {
  if ( t.getCause() instanceof ParserConfigurationException || t.getMessage().contains( "DocumentBuilder" ) ) {
    throw new KettleException( "JAXP DocumentBuilder unavailable; check parser JARs/JAXP settings", t );
  }
  throw t;
}
Defensive patterns

Strategy: try-catch

When it happens

Trigger: First access to the default DocumentBuilder on a thread (e.g. any XMLHandler.loadXML/parse call using the cached builder) when createDocumentBuilder fails — e.g. JAXP factory misconfiguration or parser instantiation failure.

Common situations: Broken or conflicting JAXP setup (system property javax.xml.parsers.DocumentBuilderFactory pointing to a missing/incompatible class), shading/fat-jar dependency conflicts shipping conflicting xml parser JARs, limited classloader environments (app servers, OSGi, certain plugin classloaders) hiding the parser classes.

Related errors

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/xml/XMLHandler.java:108

    new SimpleTimestampFormat( ValueMeta.DEFAULT_TIMESTAMP_FORMAT_MASK );
  public static final int DEFAULT_RETRY_ATTEMPTS = 2;

  /**
   * ThreadLocal cache for DocumentBuilder instances with standard configuration:
   * namespaceAware=false, deferNodeExpansion=true
   *
   * Uses ThreadLocal to provide each thread with its own DocumentBuilder instance.
   * DocumentBuilder is not thread-safe (has mutable internal state during parsing),
   * so each thread maintains its own instance to avoid synchronization overhead.
   * This eliminates expensive DocumentBuilderFactory creation (~60% overhead reduction).
   *
   * @see #getDefaultDocumentBuilder()
   */
  private static final ThreadLocal<DocumentBuilder> DEFAULT_BUILDER_CACHE = ThreadLocal.withInitial( () -> {
    try {
      return createDocumentBuilder( false, true );
    } catch ( KettleXMLException e ) {
      throw new DocumentBuilderInitializationException(
        "Failed to initialize default DocumentBuilder for XML parsing", e );
    }
  } );

  private XMLHandler() {
  }

  /**
   * The header string to specify encoding in UTF-8 for XML files
   *
   * @return The XML header.
   */
  public static String getXMLHeader() {
    return getXMLHeader( Const.XML_ENCODING );
  }

  /**
   * The header string to specify encoding in an XML file

View on GitHub (pinned to f3058517a1)