apache/hadoop · error · FileSystemAccessException

H05

H05

Error message

[{0}] validation failed, {1}

What it means

FileSystemAccessService.validateNamenode() enforces an optional NameNode whitelist: when httpfs.hadoop.name.node.whitelist is configured non-empty and does not contain '*', every requested NameNode (compared lowercased) must appear in the list, otherwise error H05 ('[<namenode>] validation failed, not in whitelist') is thrown per request and the operation is rejected.

Source

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

    if (cachedFS == null) {
      cachedFS = newCachedFS;
    }
    Configuration conf = new Configuration(namenodeConf);
    conf.set(HTTPFS_FS_USER, user);
    return cachedFS.getFileSystem(conf);
  }

  protected void closeFileSystem(FileSystem fs) throws IOException {
    if (fsCache.containsKey(fs.getConf().get(HTTPFS_FS_USER))) {
      fsCache.get(fs.getConf().get(HTTPFS_FS_USER)).release();
    }
  }

  protected void validateNamenode(String namenode) throws FileSystemAccessException {
    if (nameNodeWhitelist.size() > 0 && !nameNodeWhitelist.contains("*")) {
      if (!nameNodeWhitelist.contains(
          StringUtils.toLowerCase(namenode))) {
        throw new FileSystemAccessException(FileSystemAccessException.ERROR.H05, namenode, "not in whitelist");
      }
    }
  }

  protected void checkNameNodeHealth(FileSystem fileSystem) throws FileSystemAccessException {
  }

  @Override
  public <T> T execute(String user, final Configuration conf, final FileSystemExecutor<T> executor)
    throws FileSystemAccessException {
    Check.notEmpty(user, "user");
    Check.notNull(conf, "conf");
    Check.notNull(executor, "executor");
    if (!conf.getBoolean(FILE_SYSTEM_SERVICE_CREATED, false)) {
      throw new FileSystemAccessException(FileSystemAccessException.ERROR.H04);
    }
    if (conf.get(CommonConfigurationKeysPublic.FS_DEFAULT_NAME_KEY) == null ||
        conf.getTrimmed(CommonConfigurationKeysPublic.FS_DEFAULT_NAME_KEY).length() == 0) {

View on GitHub (pinned to 2add963021)

Solutions

1. Add the exact NameNode RPC address as sent by the client (lowercase, e.g. nn.example.com:8020) to httpfs.hadoop.name.node.whitelist, comma-separated
2. Alternatively clear the property (empty) or set it to '*' to disable the restriction
3. Match formats: normalize what clients send and what the whitelist contains (same host spelling and port)
4. Restart httpfs after changing the property

Example fix

<!-- before -->
<property><name>httpfs.hadoop.name.node.whitelist</name><value>nn1.example.com:8020</value></property>
<!-- client calls hdfs://nn2.example.com:8020 -> H05 -->

<!-- after -->
<property><name>httpfs.hadoop.name.node.whitelist</name><value>nn1.example.com:8020,nn2.example.com:8020</value></property>

import org.apache.hadoop.util.StringUtils;

Collection<String> whitelist = conf.getTrimmedStringCollection("httpfs.hadoop.name.node.whitelist");
if (!whitelist.isEmpty() && !whitelist.contains("*")) {
  String nn = StringUtils.toLowerCase(namenode); // same normalization as the service
  if (!whitelist.contains(nn)) {
    throw new IllegalArgumentException("namenode not whitelisted: " + namenode);
  }
}

try {
  fsAccess.execute(user, conf, executor);
} catch (FileSystemAccessException ex) {
  if (ex.getError() == FileSystemAccessException.ERROR.H05) {
    // client error: requested namenode not allowed; surface a 4xx, do not retry
    throw new BadRequestException("namenode not in whitelist", ex);
  }
  throw ex;
}

When it happens

Trigger: A client call (httpfs REST request carrying a namenode parameter, or execute()/createFileSystemInternal with a Configuration naming a NameNode) targets an address whose lowercase form is not listed in the comma-separated httpfs.hadoop.name.node.whitelist while the list is non-empty and not '*'.

Common situations: Whitelist enabled with specific RPC addresses but clients send a different form (hostname vs IP, port included vs not); a new cluster/NameNode added without updating the whitelist; leftover whitelist config from another environment.

Related errors

• User not in HttpFSServer admin group
• Unknown nameservice: {}
• Configuration has multiple addresses that match local node's
• Configuration dfs.namenode.rpc-address must be suffixed with
• Unexpected configuration parameters: dfs.namenode.replicatio

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