{"record":{"id":"fbb5723413631813","repo":"apache/hadoop","slug":"h05","errorCode":"H05","errorMessage":"[{0}] validation failed, {1}","messagePattern":"\\[(.+?)\\] validation failed, (.+?)","errorType":"error_code","errorClass":"FileSystemAccessException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/service/hadoop/FileSystemAccessService.java","lineNumber":322,"sourceCode":"    if (cachedFS == null) {\n      cachedFS = newCachedFS;\n    }\n    Configuration conf = new Configuration(namenodeConf);\n    conf.set(HTTPFS_FS_USER, user);\n    return cachedFS.getFileSystem(conf);\n  }\n\n  protected void closeFileSystem(FileSystem fs) throws IOException {\n    if (fsCache.containsKey(fs.getConf().get(HTTPFS_FS_USER))) {\n      fsCache.get(fs.getConf().get(HTTPFS_FS_USER)).release();\n    }\n  }\n\n  protected void validateNamenode(String namenode) throws FileSystemAccessException {\n    if (nameNodeWhitelist.size() > 0 && !nameNodeWhitelist.contains(\"*\")) {\n      if (!nameNodeWhitelist.contains(\n          StringUtils.toLowerCase(namenode))) {\n        throw new FileSystemAccessException(FileSystemAccessException.ERROR.H05, namenode, \"not in whitelist\");\n      }\n    }\n  }\n\n  protected void checkNameNodeHealth(FileSystem fileSystem) throws FileSystemAccessException {\n  }\n\n  @Override\n  public <T> T execute(String user, final Configuration conf, final FileSystemExecutor<T> executor)\n    throws FileSystemAccessException {\n    Check.notEmpty(user, \"user\");\n    Check.notNull(conf, \"conf\");\n    Check.notNull(executor, \"executor\");\n    if (!conf.getBoolean(FILE_SYSTEM_SERVICE_CREATED, false)) {\n      throw new FileSystemAccessException(FileSystemAccessException.ERROR.H04);\n    }\n    if (conf.get(CommonConfigurationKeysPublic.FS_DEFAULT_NAME_KEY) == null ||\n        conf.getTrimmed(CommonConfigurationKeysPublic.FS_DEFAULT_NAME_KEY).length() == 0) {","sourceCodeStart":304,"sourceCodeEnd":340,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/service/hadoop/FileSystemAccessService.java#L304-L340","documentation":"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.","triggerScenarios":"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 '*'.","commonSituations":"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.","solutions":["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","Alternatively clear the property (empty) or set it to '*' to disable the restriction","Match formats: normalize what clients send and what the whitelist contains (same host spelling and port)","Restart httpfs after changing the property"],"exampleFix":"<!-- before -->\n<property><name>httpfs.hadoop.name.node.whitelist</name><value>nn1.example.com:8020</value></property>\n<!-- client calls hdfs://nn2.example.com:8020 -> H05 -->\n\n<!-- after -->\n<property><name>httpfs.hadoop.name.node.whitelist</name><value>nn1.example.com:8020,nn2.example.com:8020</value></property>","handlingStrategy":"validation","validationCode":"import org.apache.hadoop.util.StringUtils;\n\nCollection<String> whitelist = conf.getTrimmedStringCollection(\"httpfs.hadoop.name.node.whitelist\");\nif (!whitelist.isEmpty() && !whitelist.contains(\"*\")) {\n  String nn = StringUtils.toLowerCase(namenode); // same normalization as the service\n  if (!whitelist.contains(nn)) {\n    throw new IllegalArgumentException(\"namenode not whitelisted: \" + namenode);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  fsAccess.execute(user, conf, executor);\n} catch (FileSystemAccessException ex) {\n  if (ex.getError() == FileSystemAccessException.ERROR.H05) {\n    // client error: requested namenode not allowed; surface a 4xx, do not retry\n    throw new BadRequestException(\"namenode not in whitelist\", ex);\n  }\n  throw ex;\n}","preventionTips":["Decide one canonical NameNode spelling (FQDN:port) and use it in both client URLs and the whitelist","Keep the whitelist lowercase - the service compares lowercased values","When adding a cluster, update httpfs.hadoop.name.node.whitelist in the same change","Prefer leaving the whitelist empty unless you specifically need the restriction"],"tags":["httpfs","whitelist","namenode","authorization","configuration"],"backgroundTag":"whitelist-rejection","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}