apache/hadoop · error · FileSystemOperationUnhandledException

An unhandled file operation exception

Error message

An unhandled file operation exception

What it means

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.

Source

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

  <T> FileSystemOperation<T> execute(
      final String scopeDescription,
      final Callable<T> callableFileOperation,
      T defaultResultValue) throws IOException {

    try {
      final T executionResult = callableFileOperation.call();
      return new FileSystemOperation<>(executionResult, null);
    } catch (AbfsRestOperationException abfsRestOperationException) {
      return new FileSystemOperation<>(defaultResultValue, abfsRestOperationException);
    } catch (AzureBlobFileSystemException azureBlobFileSystemException) {
      throw new IOException(azureBlobFileSystemException);
    } catch (Exception exception) {
      if (exception instanceof ExecutionException) {
        exception = (Exception) getRootCause(exception);
      }
      final FileSystemOperationUnhandledException fileSystemOperationUnhandledException
          = new FileSystemOperationUnhandledException(exception);
      throw new IOException(fileSystemOperationUnhandledException);
    }
  }

  private void checkCheckAccessException(final Path path,
      final AzureBlobFileSystemException exception) throws IOException {
    if (exception instanceof AbfsRestOperationException) {
      AbfsRestOperationException ere = (AbfsRestOperationException) exception;
      if (ere.getStatusCode() == HttpURLConnection.HTTP_FORBIDDEN) {
        throw (IOException) new AccessControlException(ere.getMessage())
            .initCause(exception);
      }
    }
    checkException(path, exception);
  }

  /**
   * Given a path and exception, choose which IOException subclass
   * to create.

View on GitHub (pinned to 2add963021)

Solutions

  1. Unwrap and inspect the root cause (e.getCause() chain / getRootCause) to identify the real failure.
  2. Eliminate concurrent use-after-close of the FileSystem instance (cache via FileSystem.get, do not close shared instances).
  3. Align hadoop-azure with matching hadoop-common versions; upgrade to a maintained patch release if the stack matches a known bug.

Example fix

// before
catch (IOException e) {
  LOG.error("failed: {}", e.getMessage());
}

// after
catch (IOException e) {
  Throwable root = e;
  while (root.getCause() != null) { root = root.getCause(); }
  LOG.error("root cause:", root); // report the wrapped runtime failure, not just the wrapper
}
Defensive patterns

Strategy: try-catch

Try / catch

try {
  return fs.open(path);
} catch (IOException e) {
  if (e.getCause() instanceof FileSystemOperationUnhandledException) {
    Throwable root = e.getCause().getCause();
    LOG.error("Driver-internal failure (not a service error):", root);
  }
  throw e;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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