apache/hadoop · critical · FileSystemOperationUnhandledException

An unhandled file operation exception

Error message

An unhandled file operation exception

What it means

Thrown during AzureBlobFileSystemStore initialization when constructing AbfsConfiguration from the Hadoop Configuration fails with IllegalAccessException — the reflective binding of configuration fields was denied access. It surfaces as FileSystemOperationUnhandledException ('An unhandled file operation exception'), so the filesystem fails to initialize at all. Almost always a classpath/JDK problem: mismatched hadoop-azure vs hadoop-common versions, duplicate or shaded copies of ABFS classes, or Java strong-encapsulation blocking reflective field access.

Source

Thrown at hadoop-tools/hadoop-azure/src/main/java/org/apache/hadoop/fs/azurebfs/AzureBlobFileSystemStore.java:240

   * required.
   * @param abfsStoreBuilder Builder for AzureBlobFileSystemStore.
   * @throws IOException Throw IOE in case of failure during constructing.
   */
  public AzureBlobFileSystemStore(
      AzureBlobFileSystemStoreBuilder abfsStoreBuilder) throws IOException {
    this.uri = abfsStoreBuilder.uri;
    String[] authorityParts = authorityParts(uri);
    final String fileSystemName = authorityParts[0];
    final String accountName = authorityParts[1];
    this.fsBackRef = abfsStoreBuilder.fsBackRef;

    leaseRefs = Collections.synchronizedMap(new WeakHashMap<>());

    try {
      this.abfsConfiguration = new AbfsConfiguration(abfsStoreBuilder.configuration,
          accountName, fileSystemName, getAbfsServiceTypeFromUrl());
    } catch (IllegalAccessException exception) {
      throw new FileSystemOperationUnhandledException(exception);
    }

    LOG.trace("AbfsConfiguration init complete");

    this.userGroupInformation = UserGroupInformation.getCurrentUser();
    this.userName = userGroupInformation.getShortUserName();
    LOG.trace("UGI init complete");
    if (!abfsConfiguration.getSkipUserGroupMetadataDuringInitialization()) {
      try {
        this.primaryUserGroup = userGroupInformation.getPrimaryGroupName();
      } catch (IOException ex) {
        LOG.error("Failed to get primary group for {}, using user name as primary group name", userName);
        this.primaryUserGroup = userName;
      }
    } else {
      //Provide a default group name
      this.primaryUserGroup = userName;
    }

View on GitHub (pinned to 2add963021)

Solutions

1. Align hadoop-azure and hadoop-common to the exact same Hadoop release version (check mvn dependency:tree / classpath order).
2. Remove duplicate/shaded copies of hadoop-azure classes from the application jar.
3. Prefer Hadoop's own client/shaded artifacts, or add the required --add-opens java.base/java.lang=ALL-UNNAMED on locked-down JDKs.
4. Reproduce with hadoop-azure debug logging to confirm which config field failed reflectively.

Example fix

<!-- before: mixed versions -->
<dependency><groupId>org.apache.hadoop</groupId><artifactId>hadoop-azure</artifactId><version>3.3.4</version></dependency>
<dependency><groupId>org.apache.hadoop</groupId><artifactId>hadoop-common</artifactId><version>3.2.1</version></dependency>

<!-- after: aligned versions -->
<dependency><groupId>org.apache.hadoop</groupId><artifactId>hadoop-azure</artifactId><version>3.3.4</version></dependency>
<dependency><groupId>org.apache.hadoop</groupId><artifactId>hadoop-common</artifactId><version>3.3.4</version></dependency>

// build-time consistency check
// mvn dependency:tree -Dincludes=org.apache.hadoop:hadoop-common,org.apache.hadoop:hadoop-azure
// runtime check that classes load from a single source
Class<?> a = Class.forName("org.apache.hadoop.fs.azurebfs.AzureBlobFileSystem");
Class<?> b = Class.forName("org.apache.hadoop.conf.Configuration");
// verify both come from the expected Hadoop distribution/version in your runtime

try {
  return FileSystem.get(uri, conf);
} catch (IOException e) {
  if (e.getCause() instanceof FileSystemOperationUnhandledException
      && e.getCause().getCause() instanceof IllegalAccessException) {
    throw new IllegalStateException("hadoop-azure/hadoop-common version mismatch on classpath", e);
  }
  throw e;
}

When it happens

Trigger: Calling FileSystem.get (or new AzureBlobFileSystem().initialize) with hadoop-azure and hadoop-common from different Hadoop releases on the classpath, duplicate ABFS classes in a fat jar, or a JDK/module configuration that denies reflective access to AbfsConfiguration fields.

Common situations: Upgrading hadoop-azure without upgrading the runtime hadoop-common; application fat jars embedding an extra hadoop-azure copy; running on newer JDKs with restricted --add-opens; shade plugins rewriting reflection-referenced classes.

Related errors

• Cannot initialize the class: {clazz}
• Failed to instantiate comparator: {comparator}({e})
• Unbound ${method}
• Error creating plugin: {}
• Cannot find method: {name}

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