{"record":{"id":"481be514a158b2e3","repo":"apache/hadoop","slug":"failed-to-read-type-node-list-from-file-filena","errorCode":null,"errorMessage":"Failed to read {type} node list from file: {filename}","messagePattern":"Failed to read (.+?) node list from file: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/balancer/Balancer.java","lineNumber":1234,"sourceCode":"      }\n      return b.build();\n    }\n\n    private static int processHostList(String[] args, int i, String type,\n        Set<String> nodes) {\n      Preconditions.checkArgument(++i < args.length,\n          \"List of %s nodes | -f <filename> is missing: args=%s\",\n          type, Arrays.toString(args));\n      if (\"-f\".equalsIgnoreCase(args[i])) {\n        Preconditions.checkArgument(++i < args.length,\n            \"File containing %s nodes is not specified: args=%s\",\n            type, Arrays.toString(args));\n\n        final String filename = args[i];\n        try {\n          HostsFileReader.readFileToSet(type, filename, nodes);\n        } catch (IOException e) {\n          throw new IllegalArgumentException(\n              \"Failed to read \" + type + \" node list from file: \" + filename);\n        }\n      } else {\n        final String[] addresses = StringUtils.getTrimmedStrings(args[i]);\n        nodes.addAll(Arrays.asList(addresses));\n      }\n      return i;\n    }\n\n    private static Set<String> parseBlockPoolList(String string) {\n      String[] addrs = StringUtils.getTrimmedStrings(string);\n      return new HashSet<String>(Arrays.asList(addrs));\n    }\n\n    private static void printUsage(PrintStream out) {\n      out.println(USAGE + \"\\n\");\n    }\n  }","sourceCodeStart":1216,"sourceCodeEnd":1252,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/balancer/Balancer.java#L1216-L1252","documentation":"Thrown when HostsFileReader.readFileToSet(type, filename, nodes) raises IOException while loading a node-list file given via '-f <filename>' after one of the node-filter options (-include/-exclude/-source/-excludeSource/-target/-excludeTarget). The IOException is wrapped in IllegalArgumentException naming the list type and file path. readFileToSet opens a plain local file, so the file must exist and be readable on the gateway machine running the balancer - not in HDFS.","triggerScenarios":"Passing e.g. 'hdfs balancer -include -f /tmp/inc.txt' where the file is missing, unreadable (permissions), points to an HDFS path, or the path has a typo. Any open/read IOException from the local filesystem triggers it.","commonSituations":"Operators assuming '-f' reads from HDFS; files staged on a different gateway than where the balancer job runs; permission mismatches when the balancer runs as a different user; cron environments with a different working directory and relative paths.","solutions":["Verify the file exists and is readable by the balancer user on the exact machine where the balancer runs (use an absolute path)","Use one host (optionally host:port or host:storageType per line for include/exclude lists) per line","If the list lives in HDFS, copy it to local disk first, e.g. 'hdfs dfs -get /ops/balancer-include.txt /tmp/inc.txt', then pass the local path"],"exampleFix":"# before\nhdfs balancer -include -f /ops/include.txt   # HDFS path, fails\n\n# after\nhdfs dfs -get /ops/include.txt /tmp/include.txt\nhdfs balancer -include -f /tmp/include.txt","handlingStrategy":"validation","validationCode":"static Path validateNodeListFile(String filename) {\n  Path p = Paths.get(filename);\n  if (!Files.isRegularFile(p) || !Files.isReadable(p)) {\n    throw new IllegalArgumentException(\"Node list file missing/unreadable (must be local): \" + p);\n  }\n  return p;\n}","typeGuard":null,"tryCatchPattern":"catch (IllegalArgumentException e) { log.error(\"Could not load node list: {}\", e.getMessage()); System.exit(-1); }","preventionTips":["Always pass absolute local paths for -f node lists; stage from HDFS with hdfs dfs -get first","Pre-check existence and permissions in the invoking script with the validation helper"],"tags":["hdfs","balancer","cli","file-io","node-filter"],"backgroundTag":"input-file-read-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}