apache/hadoop · error · IllegalArgumentException

Illegal principal name " + name + ": " + ioe.toString()

Error message

Illegal principal name " + name + ": " + ioe.toString()

What it means

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.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/User.java:50

 */
@InterfaceAudience.LimitedPrivate({"HDFS", "MapReduce"})
@InterfaceStability.Evolving
class User implements Principal {
  private final String fullName;
  private final String shortName;
  private volatile AuthenticationMethod authMethod = null;
  private volatile LoginContext login = null;
  private volatile long lastLogin = 0;

  public User(String name) {
    this(name, null, null);
  }
  
  public User(String name, AuthenticationMethod authMethod, LoginContext login) {
    try {
      shortName = new HadoopKerberosName(name).getShortName();
    } catch (IOException ioe) {
      throw new IllegalArgumentException("Illegal principal name " + name
                                         +": " + ioe.toString(), ioe);
    }
    fullName = name;

    this.authMethod = authMethod;
    this.login = login;
  }

  /**
   * Get the full name of the user.
   */
  @Override
  public String getName() {
    return fullName;
  }
  
  /**
   * Get the user name up to the first '/' or '@'

View on GitHub (pinned to 2add963021)

Solutions

1. Test the name directly: `hadoop org.apache.hadoop.security.HadoopKerberosName 'user@REALM'` prints the parse failure and the translated short name
2. Fix or simplify hadoop.security.auth_to_local rules and keep a trailing DEFAULT entry
3. Escape XML-special characters inside rule regexes in core-site.xml (& as &amp;, < as &lt;)
4. If Kerberos translation is not needed (simple auth RPC), pass a plain alphanumeric short name instead of a full principal

Example fix

// before
UserGroupInformation.createRemoteUser("host/fqdn@REALM.EXAMPLE.COM", AuthMethod.SIMPLE);
// after: pre-translate the name (or fix auth_to_local) so rule application cannot fail
String shortName = new HadoopKerberosName("host/fqdn@REALM.EXAMPLE.COM").getShortName();
UserGroupInformation.createRemoteUser(shortName, AuthMethod.SIMPLE);

static boolean isTranslatablePrincipal(String name) {
  try {
    new HadoopKerberosName(name).getShortName();
    return true;
  } catch (IOException e) {
    return false;
  }
}

try {
  return UserGroupInformation.createRemoteUser(name, authMethod);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("rejecting identity '" + name
      + "': principal not translatable by auth_to_local", e);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Problem with Kerberos auth_to_local name configuration
• Failed to find user in name " + subject
• Invalid attribute value for hadoop.kerberos.min.seconds.befo
• Subject must not be null
• Provided Subject must contain a KerberosPrincipal

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/42924962b2a87f3f. Report an issue: GitHub.