{"record":{"id":"400435e13ef5dd3b","repo":"apache/hadoop","slug":"an-unhandled-file-operation-exception-400435","errorCode":null,"errorMessage":"An unhandled file operation exception","messagePattern":"An unhandled file operation exception","errorType":"exception","errorClass":"FileSystemOperationUnhandledException","httpStatus":null,"severity":"critical","filePath":"hadoop-tools/hadoop-azure/src/main/java/org/apache/hadoop/fs/azurebfs/AzureBlobFileSystemStore.java","lineNumber":240,"sourceCode":"   * required.\n   * @param abfsStoreBuilder Builder for AzureBlobFileSystemStore.\n   * @throws IOException Throw IOE in case of failure during constructing.\n   */\n  public AzureBlobFileSystemStore(\n      AzureBlobFileSystemStoreBuilder abfsStoreBuilder) throws IOException {\n    this.uri = abfsStoreBuilder.uri;\n    String[] authorityParts = authorityParts(uri);\n    final String fileSystemName = authorityParts[0];\n    final String accountName = authorityParts[1];\n    this.fsBackRef = abfsStoreBuilder.fsBackRef;\n\n    leaseRefs = Collections.synchronizedMap(new WeakHashMap<>());\n\n    try {\n      this.abfsConfiguration = new AbfsConfiguration(abfsStoreBuilder.configuration,\n          accountName, fileSystemName, getAbfsServiceTypeFromUrl());\n    } catch (IllegalAccessException exception) {\n      throw new FileSystemOperationUnhandledException(exception);\n    }\n\n    LOG.trace(\"AbfsConfiguration init complete\");\n\n    this.userGroupInformation = UserGroupInformation.getCurrentUser();\n    this.userName = userGroupInformation.getShortUserName();\n    LOG.trace(\"UGI init complete\");\n    if (!abfsConfiguration.getSkipUserGroupMetadataDuringInitialization()) {\n      try {\n        this.primaryUserGroup = userGroupInformation.getPrimaryGroupName();\n      } catch (IOException ex) {\n        LOG.error(\"Failed to get primary group for {}, using user name as primary group name\", userName);\n        this.primaryUserGroup = userName;\n      }\n    } else {\n      //Provide a default group name\n      this.primaryUserGroup = userName;\n    }","sourceCodeStart":222,"sourceCodeEnd":258,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-tools/hadoop-azure/src/main/java/org/apache/hadoop/fs/azurebfs/AzureBlobFileSystemStore.java#L222-L258","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Align hadoop-azure and hadoop-common to the exact same Hadoop release version (check mvn dependency:tree / classpath order).","Remove duplicate/shaded copies of hadoop-azure classes from the application jar.","Prefer Hadoop's own client/shaded artifacts, or add the required --add-opens java.base/java.lang=ALL-UNNAMED on locked-down JDKs.","Reproduce with hadoop-azure debug logging to confirm which config field failed reflectively."],"exampleFix":"<!-- before: mixed versions -->\n<dependency><groupId>org.apache.hadoop</groupId><artifactId>hadoop-azure</artifactId><version>3.3.4</version></dependency>\n<dependency><groupId>org.apache.hadoop</groupId><artifactId>hadoop-common</artifactId><version>3.2.1</version></dependency>\n\n<!-- after: aligned versions -->\n<dependency><groupId>org.apache.hadoop</groupId><artifactId>hadoop-azure</artifactId><version>3.3.4</version></dependency>\n<dependency><groupId>org.apache.hadoop</groupId><artifactId>hadoop-common</artifactId><version>3.3.4</version></dependency>","handlingStrategy":"validation","validationCode":"// build-time consistency check\n// mvn dependency:tree -Dincludes=org.apache.hadoop:hadoop-common,org.apache.hadoop:hadoop-azure\n// runtime check that classes load from a single source\nClass<?> a = Class.forName(\"org.apache.hadoop.fs.azurebfs.AzureBlobFileSystem\");\nClass<?> b = Class.forName(\"org.apache.hadoop.conf.Configuration\");\n// verify both come from the expected Hadoop distribution/version in your runtime","typeGuard":null,"tryCatchPattern":"try {\n  return FileSystem.get(uri, conf);\n} catch (IOException e) {\n  if (e.getCause() instanceof FileSystemOperationUnhandledException\n      && e.getCause().getCause() instanceof IllegalAccessException) {\n    throw new IllegalStateException(\"hadoop-azure/hadoop-common version mismatch on classpath\", e);\n  }\n  throw e;\n}","preventionTips":["Pin all org.apache.hadoop artifacts to one release version via dependencyManagement.","Audit fat jars for duplicate hadoop-azure/hadoop-common classes.","Run integration tests on the same JDK and classpath as production."],"tags":["azure-abfs","classpath","version-conflict","initialization","reflection"],"backgroundTag":"classpath-version-conflict","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}