{"record":{"id":"4ac021f78da44ba2","repo":"apache/hadoop","slug":"configuration-hadoop-user-group-static-mapping-ove","errorCode":null,"errorMessage":"Configuration hadoop.user.group.static.mapping.overrides is invalid","messagePattern":"Configuration hadoop\\.user\\.group\\.static\\.mapping\\.overrides is invalid","errorType":"exception","errorClass":"HadoopIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/Groups.java","lineNumber":175,"sourceCode":"    return negativeCache;\n  }\n\n  /*\n   * Parse the hadoop.user.group.static.mapping.overrides configuration to\n   * staticUserToGroupsMap\n   */\n  private void parseStaticMapping(Configuration conf) {\n    String staticMapping = conf.get(\n        CommonConfigurationKeys.HADOOP_USER_GROUP_STATIC_OVERRIDES,\n        CommonConfigurationKeys.HADOOP_USER_GROUP_STATIC_OVERRIDES_DEFAULT);\n    Collection<String> mappings = StringUtils.getStringCollection(\n        staticMapping, \";\");\n    Map<String, Set<String>> staticUserToGroupsMap = new HashMap<>();\n    for (String users : mappings) {\n      Collection<String> userToGroups = StringUtils.getStringCollection(users,\n          \"=\");\n      if (userToGroups.size() < 1 || userToGroups.size() > 2) {\n        throw new HadoopIllegalArgumentException(\"Configuration \"\n            + CommonConfigurationKeys.HADOOP_USER_GROUP_STATIC_OVERRIDES\n            + \" is invalid\");\n      }\n      String[] userToGroupsArray = userToGroups.toArray(new String[userToGroups\n          .size()]);\n      String user = userToGroupsArray[0];\n      Set<String> groups = Collections.emptySet();\n      if (userToGroupsArray.length == 2) {\n        groups = new LinkedHashSet(StringUtils\n            .getStringCollection(userToGroupsArray[1]));\n      }\n      staticUserToGroupsMap.put(user, groups);\n    }\n    staticMapRef.set(\n        staticUserToGroupsMap.isEmpty() ? null : staticUserToGroupsMap);\n  }\n\n  private boolean isNegativeCacheEnabled() {","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/Groups.java#L157-L193","documentation":"Groups (Hadoop's group-mapping service) parses hadoop.user.group.static.mapping.overrides at construction. The value is ';'-separated entries, each either 'user' (maps to empty group set) or 'user=group1,group2'. If any entry splits on '=' into zero parts or more than two parts, a HadoopIllegalArgumentException is thrown with this message. This fails fast at first group lookup, so it typically breaks NameNode/DataNode/JobTracker startup or the first UGI group resolution.","triggerScenarios":"Config values like 'user=g1=g2' (two '=' signs, size 3), a trailing ';' producing an empty entry, or whitespace-only entries — StringUtils.getStringCollection yields malformed token counts. Any single bad entry poisons the whole property.","commonSituations":"Operators adding static overrides with '=' inside group DNs (LDAP-style 'CN=g,OU=x' unescaped); copy-paste from docs leaving 'user=' placeholders; scripts concatenating entries with stray semicolons; XML entity mistakes (& not escaped) truncating entries.","solutions":["Fix the value to the strict 'user=group1,group2;user2=group3' format: exactly one '=' per entry, entries separated by ';', no trailing separators","To map a user to no groups use the bare 'user' form (no '=' at all)","Escape or drop '=' characters inside group names; they cannot appear in this simple format","Restart the service after editing core-site.xml — the parse happens once in the Groups singleton"],"exampleFix":"# before (core-site.xml)\n<property><name>hadoop.user.group.static.mapping.overrides</name>\n  <value>alice=hdfs,users=bobs;bob=</value></property>\n\n# after\n<property><name>hadoop.user.group.static.mapping.overrides</name>\n  <value>alice=hdfs,users;bob=hdfs</value></property>","handlingStrategy":"validation","validationCode":"static void validateStaticMapping(String v) {\n  for (String entry : v.split(\";\")) {\n    if (entry.isEmpty()) continue;\n    String[] parts = entry.split(\"=\", -1);\n    if (parts.length > 2) {\n      throw new IllegalArgumentException(\"Bad entry (multiple '='): \" + entry);\n    }\n  }\n}\nString v = conf.get(\"hadoop.user.group.static.mapping.overrides\", \"\");\nvalidateStaticMapping(v);\nnew Groups(conf); // safe now","typeGuard":null,"tryCatchPattern":"try {\n  Groups.getUserToGroupsMappingService(conf);\n} catch (HadoopIllegalArgumentException e) {\n  // fix hadoop.user.group.static.mapping.overrides formatting\n  LOG.error(\"Invalid static mapping overrides: {}\", e.getMessage());\n}","preventionTips":["One '=' per entry, ';' between entries, no trailing ';'; bare 'user' means empty group set","Never put '=' inside group names — use different separators in directory data","Lint site-wide core-site.xml for this key before rollout"],"tags":["configuration","group-mapping","core-site","hadoop"],"backgroundTag":"config-parse-invalid","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}