{"record":{"id":"472308bc56907ab5","repo":"pentaho/pentaho-kettle","slug":"failed-to-initialize-default-documentbuilder-for-xml-parsing","errorCode":null,"errorMessage":"Failed to initialize default DocumentBuilder for XML parsing","messagePattern":"Failed to initialize default DocumentBuilder for XML parsing","errorType":"exception","errorClass":"DocumentBuilderInitializationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/xml/XMLHandler.java","lineNumber":108,"sourceCode":"    new SimpleTimestampFormat( ValueMeta.DEFAULT_TIMESTAMP_FORMAT_MASK );\n  public static final int DEFAULT_RETRY_ATTEMPTS = 2;\n\n  /**\n   * ThreadLocal cache for DocumentBuilder instances with standard configuration:\n   * namespaceAware=false, deferNodeExpansion=true\n   *\n   * Uses ThreadLocal to provide each thread with its own DocumentBuilder instance.\n   * DocumentBuilder is not thread-safe (has mutable internal state during parsing),\n   * so each thread maintains its own instance to avoid synchronization overhead.\n   * This eliminates expensive DocumentBuilderFactory creation (~60% overhead reduction).\n   *\n   * @see #getDefaultDocumentBuilder()\n   */\n  private static final ThreadLocal<DocumentBuilder> DEFAULT_BUILDER_CACHE = ThreadLocal.withInitial( () -> {\n    try {\n      return createDocumentBuilder( false, true );\n    } catch ( KettleXMLException e ) {\n      throw new DocumentBuilderInitializationException(\n        \"Failed to initialize default DocumentBuilder for XML parsing\", e );\n    }\n  } );\n\n  private XMLHandler() {\n  }\n\n  /**\n   * The header string to specify encoding in UTF-8 for XML files\n   *\n   * @return The XML header.\n   */\n  public static String getXMLHeader() {\n    return getXMLHeader( Const.XML_ENCODING );\n  }\n\n  /**\n   * The header string to specify encoding in an XML file","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/xml/XMLHandler.java#L90-L126","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped cause (getCause()) — the KettleXMLException/ParserConfigurationException names the real factory failure","Check/unset javax.xml.parsers.DocumentBuilderFactory system properties that override the default JAXP factory","Remove conflicting XML parser JARs from the classpath (xerces/rt conflicts, shaded duplicates)","Ensure the parser classes are visible to the thread's classloader (correct plugin/lib packaging)","Catch the exception on first parse and fall back to an explicitly created DocumentBuilder"],"exampleFix":"// before\nDocument doc = XMLHandler.loadXMLString( xml ); // may blow up in cache init\n// after\ntry {\n  Document doc = XMLHandler.loadXMLString( xml );\n} catch ( Throwable t ) {\n  if ( t.getCause() instanceof ParserConfigurationException || t.getMessage().contains( \"DocumentBuilder\" ) ) {\n    throw new KettleException( \"JAXP DocumentBuilder unavailable; check parser JARs/JAXP settings\", t );\n  }\n  throw t;\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["xml","initialization","jaxp","classpath"],"backgroundTag":"module-init-failed","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}