{"record":{"id":"6c8addd03c11b800","repo":"apache/hadoop","slug":"an-unhandled-file-operation-exception","errorCode":null,"errorMessage":"An unhandled file operation exception","messagePattern":"An unhandled file operation exception","errorType":"exception","errorClass":"FileSystemOperationUnhandledException","httpStatus":null,"severity":"error","filePath":"hadoop-tools/hadoop-azure/src/main/java/org/apache/hadoop/fs/azurebfs/AzureBlobFileSystem.java","lineNumber":1658,"sourceCode":"  <T> FileSystemOperation<T> execute(\n      final String scopeDescription,\n      final Callable<T> callableFileOperation,\n      T defaultResultValue) throws IOException {\n\n    try {\n      final T executionResult = callableFileOperation.call();\n      return new FileSystemOperation<>(executionResult, null);\n    } catch (AbfsRestOperationException abfsRestOperationException) {\n      return new FileSystemOperation<>(defaultResultValue, abfsRestOperationException);\n    } catch (AzureBlobFileSystemException azureBlobFileSystemException) {\n      throw new IOException(azureBlobFileSystemException);\n    } catch (Exception exception) {\n      if (exception instanceof ExecutionException) {\n        exception = (Exception) getRootCause(exception);\n      }\n      final FileSystemOperationUnhandledException fileSystemOperationUnhandledException\n          = new FileSystemOperationUnhandledException(exception);\n      throw new IOException(fileSystemOperationUnhandledException);\n    }\n  }\n\n  private void checkCheckAccessException(final Path path,\n      final AzureBlobFileSystemException exception) throws IOException {\n    if (exception instanceof AbfsRestOperationException) {\n      AbfsRestOperationException ere = (AbfsRestOperationException) exception;\n      if (ere.getStatusCode() == HttpURLConnection.HTTP_FORBIDDEN) {\n        throw (IOException) new AccessControlException(ere.getMessage())\n            .initCause(exception);\n      }\n    }\n    checkException(path, exception);\n  }\n\n  /**\n   * Given a path and exception, choose which IOException subclass\n   * to create.","sourceCodeStart":1640,"sourceCodeEnd":1676,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-tools/hadoop-azure/src/main/java/org/apache/hadoop/fs/azurebfs/AzureBlobFileSystem.java#L1640-L1676","documentation":"Thrown by AzureBlobFileSystem's executeFileSystemOperation wrapper when an operation fails with an exception that is neither AbfsRestOperationException nor AzureBlobFileSystemException — i.e., an unexpected runtime failure (NPE, IllegalStateException, interrupted execution after unwrapping the ExecutionException root cause). It is wrapped in FileSystemOperationUnhandledException ('An unhandled file operation exception') and rethrown as IOException. This marks a bug or environment problem inside the driver, not a service-returned error, so retrying usually will not help.","triggerScenarios":"Any AzureBlobFileSystem read/write/status operation whose callable throws a runtime exception — e.g., concurrent use of the filesystem after close(), thread interruption, or a driver-internal defect.","commonSituations":"Sharing a FileSystem instance across threads while one closes it; job tasks cancelled mid-operation; version mismatches between hadoop-azure and its dependencies causing NPEs in new code paths.","solutions":["Unwrap and inspect the root cause (e.getCause() chain / getRootCause) to identify the real failure.","Eliminate concurrent use-after-close of the FileSystem instance (cache via FileSystem.get, do not close shared instances).","Align hadoop-azure with matching hadoop-common versions; upgrade to a maintained patch release if the stack matches a known bug."],"exampleFix":"// before\ncatch (IOException e) {\n  LOG.error(\"failed: {}\", e.getMessage());\n}\n\n// after\ncatch (IOException e) {\n  Throwable root = e;\n  while (root.getCause() != null) { root = root.getCause(); }\n  LOG.error(\"root cause:\", root); // report the wrapped runtime failure, not just the wrapper\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  return fs.open(path);\n} catch (IOException e) {\n  if (e.getCause() instanceof FileSystemOperationUnhandledException) {\n    Throwable root = e.getCause().getCause();\n    LOG.error(\"Driver-internal failure (not a service error):\", root);\n  }\n  throw e;\n}","preventionTips":["Never close FileSystem instances obtained from FileSystem.get (shared cache).","Treat 'An unhandled file operation exception' as a bug report: capture the full root-cause stack.","Keep hadoop-azure and hadoop-common versions aligned to avoid reflective/runtime NPEs."],"tags":["azure-abfs","ioexception","wrapper","unexpected-exception","concurrency"],"backgroundTag":"unexpected-runtime-exception","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}