{"record":{"id":"42924962b2a87f3f","repo":"apache/hadoop","slug":"illegal-principal-name-name-ioe-tostr","errorCode":null,"errorMessage":"Illegal principal name \" + name + \": \" + ioe.toString()","messagePattern":"Illegal principal name \" \\+ name \\+ \": \" \\+ ioe\\.toString\\(\\)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/User.java","lineNumber":50,"sourceCode":" */\n@InterfaceAudience.LimitedPrivate({\"HDFS\", \"MapReduce\"})\n@InterfaceStability.Evolving\nclass User implements Principal {\n  private final String fullName;\n  private final String shortName;\n  private volatile AuthenticationMethod authMethod = null;\n  private volatile LoginContext login = null;\n  private volatile long lastLogin = 0;\n\n  public User(String name) {\n    this(name, null, null);\n  }\n  \n  public User(String name, AuthenticationMethod authMethod, LoginContext login) {\n    try {\n      shortName = new HadoopKerberosName(name).getShortName();\n    } catch (IOException ioe) {\n      throw new IllegalArgumentException(\"Illegal principal name \" + name\n                                         +\": \" + ioe.toString(), ioe);\n    }\n    fullName = name;\n\n    this.authMethod = authMethod;\n    this.login = login;\n  }\n\n  /**\n   * Get the full name of the user.\n   */\n  @Override\n  public String getName() {\n    return fullName;\n  }\n  \n  /**\n   * Get the user name up to the first '/' or '@'","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/User.java#L32-L68","documentation":"The User principal constructor converts a full principal into a short name via HadoopKerberosName (the auth_to_local rules). If applying those rules throws IOException (unparseable principal, bad rule regex, no rule matches), it is rethrown as IllegalArgumentException('Illegal principal name ...'). Any path that builds a User - UGI.createRemoteUser, createProxyUser, or the UGI constructor - can surface it.","triggerScenarios":"new User(name), UGI.createRemoteUser(user, authMethod), or createProxyUser(user, realUser) where HadoopKerberosName.getShortName() throws: the name has more components than the rules expect, a RULE regex fails to compile or apply, or rules were never initialized so the default translation rejects the name.","commonSituations":"hadoop.security.auth_to_local contains a malformed or non-matching rule and lacks a DEFAULT catch-all; unusual principal layouts (user/x/y@REALM, AD names with backslashes or spaces); auth_to_local changes across Hadoop version upgrades.","solutions":["Test the name directly: `hadoop org.apache.hadoop.security.HadoopKerberosName 'user@REALM'` prints the parse failure and the translated short name","Fix or simplify hadoop.security.auth_to_local rules and keep a trailing DEFAULT entry","Escape XML-special characters inside rule regexes in core-site.xml (& as &amp;, < as &lt;)","If Kerberos translation is not needed (simple auth RPC), pass a plain alphanumeric short name instead of a full principal"],"exampleFix":"// before\nUserGroupInformation.createRemoteUser(\"host/fqdn@REALM.EXAMPLE.COM\", AuthMethod.SIMPLE);\n// after: pre-translate the name (or fix auth_to_local) so rule application cannot fail\nString shortName = new HadoopKerberosName(\"host/fqdn@REALM.EXAMPLE.COM\").getShortName();\nUserGroupInformation.createRemoteUser(shortName, AuthMethod.SIMPLE);","handlingStrategy":"validation","validationCode":"static boolean isTranslatablePrincipal(String name) {\n  try {\n    new HadoopKerberosName(name).getShortName();\n    return true;\n  } catch (IOException e) {\n    return false;\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  return UserGroupInformation.createRemoteUser(name, authMethod);\n} catch (IllegalArgumentException e) {\n  throw new IllegalArgumentException(\"rejecting identity '\" + name\n      + \"': principal not translatable by auth_to_local\", e);\n}","preventionTips":["Always end hadoop.security.auth_to_local with DEFAULT","Validate principal strings at ingestion (one '@', limited '/' components) before they reach UGI","Test rule changes with `hadoop org.apache.hadoop.security.HadoopKerberosName <name>` before deploying"],"tags":["hadoop","kerberos","principal","auth-to-local","ugi"],"backgroundTag":"kerberos-principal-parsing-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}