{"record":{"id":"9c8e34f921ccbe97","repo":"apache/pulsar","slug":"could-not-configure-kerberos-principal-name-mappin","errorCode":null,"errorMessage":"Could not configure Kerberos principal name mapping.","messagePattern":"Could not configure Kerberos principal name mapping\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-common/src/main/java/org/apache/pulsar/common/sasl/KerberosName.java","lineNumber":114,"sourceCode":"    static {\n        try {\n            defaultRealm = getDefaultRealm2();\n        } catch (Exception ke) {\n            if ((System.getProperty(\"zookeeper.requireKerberosConfig\") != null)\n                && (System.getProperty(\"zookeeper.requireKerberosConfig\").equals(\"true\"))) {\n                throw new IllegalArgumentException(\"Can't get Kerberos configuration\", ke);\n            } else {\n                defaultRealm = \"\";\n            }\n        }\n        try {\n            // setConfiguration() will work even if the above try() fails due\n            // to a missing Kerberos configuration (unless zookeeper.requireKerberosConfig\n            // is set to true, which would not allow execution to reach here due to the\n            // throwing of an IllegalArgumentException above).\n            setConfiguration();\n        } catch (IOException e) {\n            throw new IllegalArgumentException(\"Could not configure Kerberos principal name mapping.\");\n        }\n    }\n\n    /**\n     * Create a name from the full Kerberos principal name.\n     * @param name\n     */\n    public KerberosName(String name) {\n        Matcher match = nameParser.matcher(name);\n        if (!match.matches()) {\n            if (name.contains(\"@\")) {\n                throw new IllegalArgumentException(\"Malformed Kerberos name: \" + name);\n            } else {\n                serviceName = name;\n                hostName = null;\n                realm = null;\n            }\n        } else {","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-common/src/main/java/org/apache/pulsar/common/sasl/KerberosName.java#L96-L132","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\n[realms]\n  EXAMPLE.COM = { kdc = kdc.example.com }  // auth_to_local missing/malformed\n// after\n[realms]\n  EXAMPLE.COM = {\n    kdc = kdc.example.com\n    auth_to_local = RULE:[1:$1@$0](.*@EXAMPLE.COM)s/@.*//\n    auth_to_local = DEFAULT\n  }","handlingStrategy":"validation","validationCode":"// Validate krb5.conf parses (including auth_to_local) before loading KerberosName\nProcess p = new ProcessBuilder(\"kinit\", \"-k\", \"-t\", keytab, principal).redirectErrorStream(true).start();\nif (p.waitFor() != 0) {\n    throw new IllegalStateException(\"Kerberos config/principal invalid — fix krb5.conf auth_to_local\");\n}","typeGuard":"static boolean kerberosConfigValid() {\n    try {\n        sun.security.krb5.Config.refresh();\n        return sun.security.krb5.Config.getInstance() != null;\n    } catch (Exception e) { return false; }\n}","tryCatchPattern":"try {\n    KerberosName name = new KerberosName(\"user@EXAMPLE.COM\");\n} catch (Throwable t) {\n    Throwable cause = t instanceof ExceptionInInitializerError ? t.getCause() : t;\n    log.error(\"Kerberos principal mapping failed: {}\", cause, cause);\n    throw new IllegalStateException(\"Fix krb5.conf auth_to_local rules\", cause);\n}","preventionTips":["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"],"tags":["kerberos","configuration","static-initializer"],"backgroundTag":"kerberos-principal-mapping-failed","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}