{"record":{"id":"4386c1624b6e7483","repo":"apache/hadoop","slug":"configuration-has-multiple-addresses-that-match-lo","errorCode":null,"errorMessage":"Configuration has multiple addresses that match local node's address. Please configure the system with dfs.nameservice.id and dfs.ha.namenode.id","messagePattern":"Configuration has multiple addresses that match local node's address\\. Please configure the system with dfs\\.nameservice\\.id and dfs\\.ha\\.namenode\\.id","errorType":"validation","errorClass":"HadoopIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/DFSUtil.java","lineNumber":1309,"sourceCode":"        try {\n          s = NetUtils.createSocketAddr(addr);\n        } catch (Exception e) {\n          LOG.warn(\"Exception in creating socket address \" + addr, e);\n          continue;\n        }\n        if (!s.isUnresolved() && matcher.match(s)) {\n          nameserviceId = nsId;\n          namenodeId = nnId;\n          found++;\n        }\n      }\n    }\n    if (found > 1) { // Only one address must match the local address\n      String msg = \"Configuration has multiple addresses that match \"\n          + \"local node's address. Please configure the system with \"\n          + DFS_NAMESERVICE_ID + \" and \"\n          + DFS_HA_NAMENODE_ID_KEY;\n      throw new HadoopIllegalArgumentException(msg);\n    }\n    return new String[] { nameserviceId, namenodeId };\n  }\n  \n  /**\n   * For given set of {@code keys} adds nameservice Id and or namenode Id\n   * and returns {nameserviceId, namenodeId} when address match is found.\n   * @see #getSuffixIDs(Configuration, String, String, String, AddressMatcher)\n   */\n  static String[] getSuffixIDs(final Configuration conf,\n      final InetSocketAddress address, final String... keys) {\n    AddressMatcher matcher = new AddressMatcher() {\n     @Override\n      public boolean match(InetSocketAddress s) {\n        return address.equals(s);\n      } \n    };\n    ","sourceCodeStart":1291,"sourceCodeEnd":1327,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/DFSUtil.java#L1291-L1327","documentation":"When dfs.nameservice.id and dfs.ha.namenode.id are not set, Hadoop auto-detects this node's HA identity: DFSUtil.getSuffixIDs(..., LOCAL_ADDRESS_MATCHER) matches local network addresses against the configured dfs.namenode.rpc-address.<nsId>.<nnId> entries. If more than one configured address matches the local machine, the identity is ambiguous and HadoopIllegalArgumentException is thrown instead of guessing.","triggerScenarios":"Two nameservices (or two namenode IDs) configured with the same host:port or a 0.0.0.0 wildcard address that matches the local machine; starting a NameNode/HA utility on a host whose address matches multiple dfs.namenode.rpc-address entries with no explicit dfs.nameservice.id/dfs.ha.namenode.id.","commonSituations":"Co-located HA NameNodes or shared ports; wildcard rpc-addresses in HA configs; startup scripts that never set the HA identity JVM properties; hosts with several interfaces each matching a different configured address.","solutions":["Set the identity explicitly for this node, e.g. HDFS_NAMENODE_OPTS=\"-Ddfs.nameservice.id=ns1 -Ddfs.ha.namenode.id=nn1\", or use per-host config files","Give every dfs.namenode.rpc-address.<nsId>.<nnId> a unique host:port so only one entry can match","Replace 0.0.0.0/wildcard rpc-addresses with concrete addresses in HA configurations"],"exampleFix":"// before: no explicit ids and two entries match this host\n//   dfs.namenode.rpc-address.ns1.nn1=host1:8020\n//   dfs.namenode.rpc-address.ns2.nn1=host1:8020\n// after: pin the identity when starting the NameNode\nHDFS_NAMENODE_OPTS=\"-Ddfs.nameservice.id=ns1 -Ddfs.ha.namenode.id=nn1\" hdfs --daemon start namenode","handlingStrategy":"validation","validationCode":"// Before starting a NameNode in HA, pin the identity so address matching is never consulted\nSystem.setProperty(\"dfs.nameservice.id\", \"ns1\");\nSystem.setProperty(\"dfs.ha.namenode.id\", \"nn1\");\n// or pass -Ddfs.nameservice.id=ns1 -Ddfs.ha.namenode.id=nn1 via HDFS_NAMENODE_OPTS","typeGuard":null,"tryCatchPattern":"catch (HadoopIllegalArgumentException e) during NN/HA initialization; when the message mentions 'multiple addresses', report that dfs.nameservice.id/dfs.ha.namenode.id must be set for this host rather than retrying.","preventionTips":["Always set dfs.nameservice.id and dfs.ha.namenode.id per host in deployment scripts instead of relying on auto-detection","Never use 0.0.0.0/wildcard values for dfs.namenode.rpc-address in HA clusters","Give co-located NameNodes distinct ports"],"tags":["hdfs","ha","configuration","namenode","address-matching","startup"],"backgroundTag":"ambiguous-address-resolution","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}