apache/hadoop · error · RuntimeException

Unable to create SAXParser

Error message

Unable to create SAXParser

What it means

A RuntimeException raised inside a per-thread SAXParser initializer in AbfsBlobClient. The first time a thread parses a blob-endpoint XML response (e.g. list containers / list paths), SAXParserFactory.newSAXParser() threw a SAXException, meaning the JAXP parser implementation on the classpath is broken or conflicting and no parser could be constructed for that thread.

Source

Thrown at hadoop-tools/hadoop-azure/src/main/java/org/apache/hadoop/fs/azurebfs/services/AbfsBlobClient.java:1985

          if (!XML_TAG_HDI_PERMISSION.equalsIgnoreCase(entry.getKey())) {
            value = encodeMetadataAttribute(value);
          }
        } catch (UnsupportedEncodingException e) {
          throw new InvalidAbfsRestOperationException(e);
        }
        metadataRequestHeaders.add(new AbfsHttpHeader(key, value));
      }
    }
    return metadataRequestHeaders;
  }

  private final ThreadLocal<SAXParser> saxParserThreadLocal = ThreadLocal.withInitial(() -> {
    SAXParserFactory factory = SAXParserFactory.newInstance();
    factory.setNamespaceAware(true);
    try {
      return factory.newSAXParser();
    } catch (SAXException e) {
      throw new RuntimeException("Unable to create SAXParser", e);
    } catch (ParserConfigurationException e) {
      throw new RuntimeException("Check parser configuration", e);
    }
  });

  /**
   * This will filter out all the rename pending json files in listing output.
   * @param listResultSchema List of entries returned by Blob Endpoint.
   * @param uri URI to be used for path conversion.
   * @return List of entries after removing duplicates.
   * @throws IOException if path conversion fails.
   */
  @VisibleForTesting
  public ListResponseData filterRenamePendingFiles(
      BlobListResultSchema listResultSchema, URI uri) throws IOException {
    List<VersionedFileStatus> fileStatuses = new ArrayList<>();
    Map<Path, Integer> renamePendingJsonPaths = new HashMap<>();

View on GitHub (pinned to 2add963021)

Solutions

1. Run mvn dependency:tree -Dincludes=xerces,xml-apis,xml-apis-ext and exclude duplicate parser jars so exactly one implementation remains.
2. Remove javax.xml.parsers.SAXParserFactory system properties / JVM flags that select a custom factory.
3. If shading, verify META-INF/services/javax.xml.parsers.SAXParserFactory is preserved or removed, never replaced by an incompatible provider.
4. Sanity-check the runtime: a small main() calling SAXParserFactory.newInstance().newSAXParser() must succeed before Hadoop Azure is used.

Example fix

<!-- before: old xerces shaded in transitively -->
<dependency>
  <groupId>com.example</groupId>
  <artifactId>legacy-soap</artifactId>
</dependency>
<!-- after -->
<dependency>
  <groupId>com.example</groupId>
  <artifactId>legacy-soap</artifactId>
  <exclusions>
    <exclusion><groupId>xerces</groupId><artifactId>xercesImpl</artifactId></exclusion>
    <exclusion><groupId>xml-apis</groupId><artifactId>xml-apis</artifactId></exclusion>
  </exclusions>
</dependency>

try {
  SAXParserFactory.newInstance().newSAXParser();
} catch (Exception e) {
  throw new IllegalStateException("Broken JAXP classpath for Hadoop Azure", e);
}

try {
  return blobClient.listContainers(prefix, token, tracingContext);
} catch (RuntimeException ex) {
  if (ex.getCause() instanceof SAXException) {
    throw new IllegalStateException("XML parser unavailable — fix xerces/xml-apis conflicts", ex);
  }
  throw ex;
}

When it happens

Trigger: First blob-endpoint XML-listing operation on a given thread when the JAXP factory fails to produce a parser — typically duplicate or incompatible xerces / xml-apis / xml-parser jars on the classpath, a shading step overwriting META-INF/services entries, or a -Djavax.xml.parsers.SAXParserFactory system property pointing at a broken factory.

Common situations: Application assemblies that shade in an old Xerces; app servers or frameworks bundling their own XML parser; JVMs with a corrupted or stripped JAXP implementation; CI images with unusual JDK distributions.

Related errors

• Check parser configuration
• SAXTransformer error: {}
• Unable to load user-bound SAS token provider class: {e}
• Parsing of XML List Response Failed in BlobClient.
• expected <EDITS/>

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/07e084f2008cc301. Report an issue: GitHub.