apache/hadoop · error · FileSystemAccessException

H03

H03

Error message

FileSystemExecutor error, {0}

What it means

FileSystemAccessService.execute() runs a FileSystemExecutor inside a UserGroupInformation.doAs with a filesystem obtained from the service cache; any exception that is not itself a FileSystemAccessException - typically an IOException from the HDFS operation - is wrapped as error H03 ('FileSystemExecutor error') with the original exception as parameter {0} and cause. This is the generic failure surface for every httpfs filesystem operation.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/service/hadoop/FileSystemAccessService.java:370

        public T run() throws Exception {
          FileSystem fs = createFileSystem(conf);
          Instrumentation instrumentation = getServer().get(Instrumentation.class);
          Instrumentation.Cron cron = instrumentation.createCron();
          try {
            checkNameNodeHealth(fs);
            cron.start();
            return executor.execute(fs);
          } finally {
            cron.stop();
            instrumentation.addCron(INSTRUMENTATION_GROUP, executor.getClass().getSimpleName(), cron);
            closeFileSystem(fs);
          }
        }
      });
    } catch (FileSystemAccessException ex) {
      throw ex;
    } catch (Exception ex) {
      throw new FileSystemAccessException(FileSystemAccessException.ERROR.H03, ex);
    }
  }

  public FileSystem createFileSystemInternal(String user, final Configuration conf)
    throws IOException, FileSystemAccessException {
    Check.notEmpty(user, "user");
    Check.notNull(conf, "conf");
    if (!conf.getBoolean(FILE_SYSTEM_SERVICE_CREATED, false)) {
      throw new FileSystemAccessException(FileSystemAccessException.ERROR.H04);
    }
    try {
      validateNamenode(
          new URI(conf.getTrimmed(
              CommonConfigurationKeysPublic.FS_DEFAULT_NAME_KEY)).
                  getAuthority());
      UserGroupInformation ugi = getUGI(user);
      return ugi.doAs(new PrivilegedExceptionAction<FileSystem>() {
        @Override

View on GitHub (pinned to 2add963021)

Solutions

1. Unwrap the cause: H03 carries the real exception - read its type/message (FileNotFoundException, AccessControlException, ...) and fix that underlying problem
2. Verify the path exists and the effective (doAs) user has permissions
3. Check NameNode health/safe mode and that the correct active NameNode is addressed
4. For transient causes (standby switch, safe mode), retry after resolving the cluster state

Example fix

// before
FileSystemAccess fsAccess = ...;
fsAccess.execute("alice", conf, executor); // H03 wraps FileNotFoundException

// after: fix the underlying cause (path existed only under a different user)
fsAccess.execute("hdfs", conf, executor);

// Pre-flight the operation's target when possible
if (executor instanceof PathAware) {
  Path p = ((PathAware) executor).getPath();
  // let callers verify existence/permissions cheaply before execute()
  // (existence check is best-effort; HDFS is the source of truth)
}

try {
  return fsAccess.execute(user, conf, executor);
} catch (FileSystemAccessException ex) {
  if (ex.getError() == FileSystemAccessException.ERROR.H03) {
    Throwable cause = ex.getCause();
    if (cause instanceof java.io.FileNotFoundException) { /* map to 404 */ }
    else if (cause instanceof org.apache.hadoop.security.AccessControlException) { /* map to 403 */ }
    else { /* map to 500, include cause message */ }
  }
  throw ex;
}

When it happens

Trigger: Calling FileSystemAccess.execute(user, conf, executor) where executor.execute(fs) (or the cached-filesystem acquisition/creation inside the action) throws: FileNotFoundException on a missing path, AccessControlException for permissions, RecoverableException/standby NameNode errors, checksum or quota failures, etc.

Common situations: Httpfs REST call on a deleted path; proxy-user (doAs) lacks HDFS permissions; NameNode in safe mode or standby; any HDFS client-level IOException surfacing through httpfs as a 400/exception response.

Related errors

• H08
• {} doesn't support satisfyStoragePolicy
• {} doesn't support setStoragePolicy
• {} doesn't support unsetStoragePolicy
• {} doesn't support getStoragePolicy

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