{"record":{"id":"99ecffa0b893e910","repo":"apache/hadoop","slug":"unknown-nameservice","errorCode":null,"errorMessage":"Unknown nameservice: {}","messagePattern":"Unknown nameservice: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/DFSUtil.java","lineNumber":742,"sourceCode":"  }\n\n  private static Collection<String> getParentNameServices(Configuration conf)\n      throws IOException {\n    Collection<String> parentNameServices = conf.getTrimmedStringCollection(\n        DFSConfigKeys.DFS_INTERNAL_NAMESERVICES_KEY);\n\n    if (parentNameServices.isEmpty()) {\n      parentNameServices = conf.getTrimmedStringCollection(\n          DFSConfigKeys.DFS_NAMESERVICES);\n    } else {\n      // Ensure that the internal service is indeed in the list of all available\n      // nameservices.\n      Collection<String> namespaces = conf\n          .getTrimmedStringCollection(DFSConfigKeys.DFS_NAMESERVICES);\n      Set<String> availableNameServices = new HashSet<>(namespaces);\n      for (String nsId : parentNameServices) {\n        if (!availableNameServices.contains(nsId)) {\n          throw new IOException(\"Unknown nameservice: \" + nsId);\n        }\n      }\n    }\n\n    return parentNameServices;\n  }\n\n  /**\n   * Map a logical namenode ID to its lifeline address.  Use the given\n   * nameservice if specified, or the configured one if none is given.\n   *\n   * @param conf Configuration\n   * @param nsId which nameservice nnId is a part of, optional\n   * @param nnId the namenode ID to get the service addr for\n   * @return the lifeline addr, null if it could not be determined\n   */\n  public static String getNamenodeLifelineAddr(final Configuration conf,\n      String nsId, String nnId) {","sourceCodeStart":724,"sourceCodeEnd":760,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/DFSUtil.java#L724-L760","documentation":"Thrown by DFSUtil.getParentNameServices (DFSUtil.java:726) while computing the internal nameservice list. When dfs.internal.nameservices is configured, every ID in it is validated against the full dfs.nameservices list; an ID that does not appear there is rejected with 'Unknown nameservice: <nsId>'. Both NameNode-side DFSUtil code and JournalNode (JournalNode.java:169) read dfs.internal.nameservices, so the check runs on startup of these services.","triggerScenarios":"dfs.internal.nameservices contains an ID that is missing from (or misspelled vs) dfs.nameservices, e.g. dfs.internal.nameservices=ns1,ns2 while dfs.nameservices=ns1. Occurs when building the internal RPC address map in a federated setup.","commonSituations":"Federation/Router onboarding where an internal nameservice was added to dfs.internal.nameservices but dfs.nameservices was not updated; typos or whitespace in nameservice IDs; stale IDs left after decommissioning a nameservice.","solutions":["Add the missing nameservice ID to dfs.nameservices so it contains every ID listed in dfs.internal.nameservices","Fix the typo/whitespace in the offending dfs.internal.nameservices entry so both keys agree","Remove decommissioned or renamed nameservice IDs from dfs.internal.nameservices","Restart the NameNode/JournalNode after correcting the configuration"],"exampleFix":"// before\n<property><name>dfs.internal.nameservices</name><value>ns1,ns2</value></property>\n<property><name>dfs.nameservices</name><value>ns1</value></property>\n// after\n<property><name>dfs.internal.nameservices</name><value>ns1,ns2</value></property>\n<property><name>dfs.nameservices</name><value>ns1,ns2</value></property>","handlingStrategy":"validation","validationCode":"import org.apache.hadoop.conf.Configuration;\nimport java.util.*;\n\nstatic void validateNameservices(Configuration conf) throws IOException {\n  Set<String> all = new HashSet<>(conf.getTrimmedStringCollection(\"dfs.nameservices\"));\n  for (String ns : conf.getTrimmedStringCollection(\"dfs.internal.nameservices\")) {\n    if (!all.contains(ns)) {\n      throw new IOException(\"Unknown nameservice: \" + ns\n          + \" - add it to dfs.nameservices or fix dfs.internal.nameservices\");\n    }\n  }\n}","typeGuard":null,"tryCatchPattern":"catch (IOException e) on NameNode/JournalNode startup when the message starts with 'Unknown nameservice:'; fail fast and print both dfs.internal.nameservices and dfs.nameservices values in the error report instead of retrying.","preventionTips":["Keep dfs.nameservices and dfs.internal.nameservices in the same config template so they are edited together","Validate the pair with a preflight config check (or `hdfs getconf -confKey dfs.nameservices`) before restarting services","Use a config-management layer (Ansible/Chef) that derives dfs.internal.nameservices as a subset of dfs.nameservices"],"tags":["hdfs","configuration","federation","nameservice","namenode","journalnode","startup"],"backgroundTag":"unknown-nameservice","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}