apache/pulsar · error · IllegalArgumentException

Could not configure Kerberos principal name mapping.

Error message

Could not configure Kerberos principal name mapping.

What it means

In the same static initializer, after obtaining the realm, KerberosName calls setConfiguration() to load the auth_to_local principal-name mapping rules. An IOException there means the Kerberos config / rule parsing failed; the initializer rethrows it as IllegalArgumentException('Could not configure Kerberos principal name mapping.'), which typically surfaces as ExceptionInInitializerError and can make the class unusable.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/sasl/KerberosName.java:114

    static {
        try {
            defaultRealm = getDefaultRealm2();
        } catch (Exception ke) {
            if ((System.getProperty("zookeeper.requireKerberosConfig") != null)
                && (System.getProperty("zookeeper.requireKerberosConfig").equals("true"))) {
                throw new IllegalArgumentException("Can't get Kerberos configuration", ke);
            } else {
                defaultRealm = "";
            }
        }
        try {
            // setConfiguration() will work even if the above try() fails due
            // to a missing Kerberos configuration (unless zookeeper.requireKerberosConfig
            // is set to true, which would not allow execution to reach here due to the
            // throwing of an IllegalArgumentException above).
            setConfiguration();
        } catch (IOException e) {
            throw new IllegalArgumentException("Could not configure Kerberos principal name mapping.");
        }
    }

    /**
     * Create a name from the full Kerberos principal name.
     * @param name
     */
    public KerberosName(String name) {
        Matcher match = nameParser.matcher(name);
        if (!match.matches()) {
            if (name.contains("@")) {
                throw new IllegalArgumentException("Malformed Kerberos name: " + name);
            } else {
                serviceName = name;
                hostName = null;
                realm = null;
            }
        } else {

View on GitHub (pinned to 820761864e)

Solutions

Fix the underlying IOException: validate /etc/krb5.conf readability and syntax, including auth_to_local rules in [realms]
Ensure the JVM user can read the Kerberos config files referenced (main file and includes)
Check the original stack (ExceptionInInitializerError cause) for the actual IOException detail
Verify with a minimal test: new KerberosName("user@REALM") after fixing config; consider JDK/provider compatibility if config is valid

Example fix

// before
[realms]
  EXAMPLE.COM = { kdc = kdc.example.com }  // auth_to_local missing/malformed
// after
[realms]
  EXAMPLE.COM = {
    kdc = kdc.example.com
    auth_to_local = RULE:[1:$1@$0](.*@EXAMPLE.COM)s/@.*//
    auth_to_local = DEFAULT
  }

Defensive patterns

Strategy: validation

Validate before calling

// Validate krb5.conf parses (including auth_to_local) before loading KerberosName
Process p = new ProcessBuilder("kinit", "-k", "-t", keytab, principal).redirectErrorStream(true).start();
if (p.waitFor() != 0) {
    throw new IllegalStateException("Kerberos config/principal invalid — fix krb5.conf auth_to_local");
}

Type guard

static boolean kerberosConfigValid() {
    try {
        sun.security.krb5.Config.refresh();
        return sun.security.krb5.Config.getInstance() != null;
    } catch (Exception e) { return false; }
}

Try / catch

try {
    KerberosName name = new KerberosName("user@EXAMPLE.COM");
} catch (Throwable t) {
    Throwable cause = t instanceof ExceptionInInitializerError ? t.getCause() : t;
    log.error("Kerberos principal mapping failed: {}", cause, cause);
    throw new IllegalStateException("Fix krb5.conf auth_to_local rules", cause);
}

Prevention

Validate auth_to_local rules with a kinit/kvno smoke test at deploy time
Ensure krb5.conf and included files are readable by the service user
Pin a JDK whose sun.security.krb5.Config works with your config; test on upgrade
Capture ExceptionInInitializerError cause chains to find the real IOException

When it happens

Trigger: Class-loading KerberosName when setConfiguration() throws IOException — unreadable krb5.conf discovered after realm resolution, malformed auth_to_local rules, or kerberos provider initialization failure inside sun.security.krb5.Config.

Common situations: krb5.conf readable but its referenced includes/files missing; JVM security provider changes breaking sun.security.krb5.Config; permissions on /etc/krb5.conf; partial Kerberos setup where realm is readable but rules aren't.

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/9c8e34f921ccbe97. Report an issue: GitHub.