apache/pulsar · error · IllegalArgumentException

Malformed Kerberos name: name

Error message

Malformed Kerberos name: name

What it means

KerberosName parses a Kerberos principal into service name, host, and realm. If the name contains '@' (implying a realm) but does not match the configured name parser pattern, it is considered structurally malformed and an IllegalArgumentException is thrown. Names without '@' are accepted as a bare service name with no host or realm.

Source

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

            // 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 {
            serviceName = match.group(1);
            hostName = match.group(3);
            realm = match.group(4);
        }
    }

    /**
     * Get the configured default realm.
     * @return the default realm from the krb5.conf
     */
    public String getDefaultRealm() {
        return defaultRealm;

View on GitHub (pinned to 820761864e)

Solutions

1. Fix the configured principal to match service/host@REALM format, e.g. 'client/broker.example.com@EXAMPLE.COM'
2. Remove the '@' if you intended a bare service name (no realm)
3. Check for environment-variable expansion mistakes that doubled or emptied parts of the principal
4. Verify the JAAS/GSS configuration matches the expected principal syntax

Example fix

// before
new KerberosName("client@@EXAMPLE.COM");
// after
new KerberosName("client/broker.example.com@EXAMPLE.COM");

boolean isValidKerberosName(String name) {
    return name == null || !name.contains("@")
        || name.matches("[^/@]+/[^@]+@[^@]+|[^/@]+@[^@]+|[^/@]+/[^@]+@$|[^/@]+@$|@[^@]+@|.*@@.*") == false && name.matches("[^/]+/[^@]+@[^@]+|[^/@]+@[^@]+");
}
// call before: new KerberosName(name)

boolean hasRealm(String principal) {
    return principal != null && principal.indexOf('@') == principal.lastIndexOf('@') && principal.indexOf('@') > 0;
}

try {
    KerberosName k = new KerberosName(name);
} catch (IllegalArgumentException e) {
    log.error("Malformed principal '{}': expected service[/host]@REALM", name);
}

When it happens

Trigger: Calling new KerberosName(String) with a string containing '@' whose overall form (service/host@REALM with optional components) fails the nameParser regex, e.g. 'user@@REALM', '@REALM', or 'svc/host@REALM@EXTRA'.

Common situations: Misconfigured principal settings in Pulsar SASL/Kerberos authentication config; copy-pasted principals with doubled '@'; environment-variable substitution leaving '@' with an empty user part.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• error while booting GSSAPI client
• loginContext name (JAAS file section header) was null. Pleas
• Invalid rule: remaining
• Authentication use SASL/JAAS/GSSAPI but server not have Prin
• Unrecognized SASL GSSAPI Server Callback.

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