{"record":{"id":"e73df026372ca425","repo":"apache/hadoop","slug":"configuration-dfs-namenode-rpc-address-must-be-suf","errorCode":null,"errorMessage":"Configuration dfs.namenode.rpc-address must be suffixed with nameservice and namenode ID for HA configuration.","messagePattern":"Configuration dfs\\.namenode\\.rpc-address must be suffixed with nameservice and namenode ID for HA configuration\\.","errorType":"exception","errorClass":"HadoopIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/HAUtil.java","lineNumber":135,"sourceCode":"   * returns the namenode Id from the corresponding configuration key.\n   * \n   * @param conf Configuration\n   * @return namenode Id on success, null on failure.\n   * @throws HadoopIllegalArgumentException on error\n   */\n  public static String getNameNodeId(Configuration conf, String nsId) {\n    String namenodeId = conf.getTrimmed(DFS_HA_NAMENODE_ID_KEY);\n    if (namenodeId != null) {\n      return namenodeId;\n    }\n    \n    String suffixes[] = DFSUtil.getSuffixIDs(conf, DFS_NAMENODE_RPC_ADDRESS_KEY,\n        nsId, null, DFSUtil.LOCAL_ADDRESS_MATCHER);\n    if (suffixes == null) {\n      String msg = \"Configuration \" + DFS_NAMENODE_RPC_ADDRESS_KEY + \n          \" must be suffixed with nameservice and namenode ID for HA \" +\n          \"configuration.\";\n      throw new HadoopIllegalArgumentException(msg);\n    }\n    \n    return suffixes[1];\n  }\n\n  /**\n   * Similar to\n   * {@link DFSUtil#getNameServiceIdFromAddress(Configuration, \n   * InetSocketAddress, String...)}\n   */\n  public static String getNameNodeIdFromAddress(final Configuration conf, \n      final InetSocketAddress address, String... keys) {\n    // Configuration with a single namenode and no nameserviceId\n    String[] ids = DFSUtil.getSuffixIDs(conf, address, keys);\n    if (ids != null && ids.length > 1) {\n      return ids[1];\n    }\n    return null;","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/HAUtil.java#L117-L153","documentation":"HAUtil.getNameNodeId returns dfs.ha.namenode.id if set; otherwise it tries to infer the namenode ID by matching local addresses against dfs.namenode.rpc-address.<nsId>.<nnId> via DFSUtil.getSuffixIDs with LOCAL_ADDRESS_MATCHER. If NO configured address matches this machine, the suffix lookup returns null and HadoopIllegalArgumentException is thrown demanding suffixed rpc-address configuration.","triggerScenarios":"Initializing HA components without dfs.ha.namenode.id while this host's address matches none of the configured dfs.namenode.rpc-address.<nsId>.<nnId> entries (wrong host, other node's address, unresolved hostname). Note the contrast: zero matches gives this error, multiple matches gives the 'multiple addresses' error.","commonSituations":"First-time HA setup missing the namenode id property; config cloned from another node so rpc-addresses point elsewhere; hostname/DNS changes (hostname -f no longer equal to the configured host); starting the NameNode on the wrong machine.","solutions":["Set dfs.ha.namenode.id explicitly for this node, e.g. HDFS_NAMENODE_OPTS=\"-Ddfs.ha.namenode.id=nn1\" (and dfs.nameservice.id for federated setups)","Fix dfs.namenode.rpc-address.<nsId>.<nnId> so this host's real address appears exactly once per nameservice","Verify name resolution: compare `hostname -f` output and /etc/hosts against the configured addresses"],"exampleFix":"// before: no id set and dfs.namenode.rpc-address.ns1.nn2=otherhost:8020 (not this machine)\n// after\nHDFS_NAMENODE_OPTS=\"-Ddfs.nameservice.id=ns1 -Ddfs.ha.namenode.id=nn1\" hdfs --daemon start namenode","handlingStrategy":"validation","validationCode":"// Preflight before any HAUtil call that infers identity\nString nnId = conf.getTrimmed(\"dfs.ha.namenode.id\");\nif (nnId == null) {\n  // ensure one dfs.namenode.rpc-address.<nsId>.<nnId> resolves to THIS host,\n  // otherwise the inference will return null and HAUtil throws\n  String local = java.net.InetAddress.getLocalHost().getCanonicalHostName();\n  boolean matches = false;\n  for (java.util.Map.Entry<String, String> e : conf) { // iterate suffixed keys\n    if (e.getKey().startsWith(\"dfs.namenode.rpc-address.\") && e.getValue().startsWith(local)) {\n      matches = true; break;\n    }\n  }\n  if (!matches) throw new IllegalStateException(\n      \"Set dfs.ha.namenode.id (and dfs.nameservice.id) for host \" + local);\n}","typeGuard":null,"tryCatchPattern":"catch (HadoopIllegalArgumentException e) on HA initialization; when the message names dfs.namenode.rpc-address suffixing, set dfs.ha.namenode.id explicitly rather than editing addresses by trial and error.","preventionTips":["Set the HA identity JVM properties in every per-host start script; do not rely on address matching","Smoke-test hostname resolution (hostname -f vs configured rpc-address hosts) as part of node provisioning"],"tags":["hdfs","ha","configuration","namenode","rpc-address","startup"],"backgroundTag":"missing-required-configuration","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}