apache/cassandra · error · AuthenticationException

Credential format error: username or password is empty or co

Error message

Credential format error: username or password is empty or contains NUL(\0) character

What it means

PasswordAuthenticator's PLAIN SASL token is expected as authzid NUL authcid NUL password. decodeCredentials() scans the token for NUL separators; if it finds more segments than allowed (i.e. a NUL embedded in a credential), the structure is invalid and AuthenticationException is thrown.

Source

Thrown at src/java/org/apache/cassandra/auth/PasswordAuthenticator.java:346

         * @throws org.apache.cassandra.exceptions.AuthenticationException if either the
         *         authnId or password is null
         */
        private void decodeCredentials(byte[] bytes) throws AuthenticationException
        {
            logger.trace("Decoding credentials from client token");
            byte[] user = null;
            byte[] pass = null;
            int end = bytes.length;
            for (int i = bytes.length - 1; i >= 0; i--)
            {
                if (bytes[i] == NUL)
                {
                    if (pass == null)
                        pass = Arrays.copyOfRange(bytes, i + 1, end);
                    else if (user == null)
                        user = Arrays.copyOfRange(bytes, i + 1, end);
                    else
                        throw new AuthenticationException("Credential format error: username or password is empty or contains NUL(\\0) character");

                    end = i;
                }
            }

            if (pass == null || pass.length == 0)
                throw new AuthenticationException("Password must not be null");
            if (user == null || user.length == 0)
                throw new AuthenticationException("Authentication ID must not be null");

            username = new String(user, StandardCharsets.UTF_8);
            password = new String(pass, StandardCharsets.UTF_8);
        }
    }

    public static class CredentialsCache extends AuthCache<String, String> implements CredentialsCacheMBean
    {
        private CredentialsCache(PasswordAuthenticator authenticator)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Remove NUL characters from the username/password before constructing the PLAIN token
  2. Encode the token as exactly: UTF8(authzid) 0x00 UTF8(authcid) 0x00 UTF8(password)
  3. Check the driver's SASL/PLAIN credential encoding helper rather than building bytes manually

Example fix

// before
String token = authzid + "\0" + userWithNul + "\0" + pass;
// after
String cleanUser = userWithNul.replace("\0", "");
String token = authzid + "\0" + cleanUser + "\0" + pass;
Defensive patterns

Strategy: validation

Validate before calling

if (user.indexOf('\0') >= 0 || pass.indexOf('\0') >= 0) throw new IllegalArgumentException("credentials must not contain NUL");

Type guard

boolean isPlainSafe(String s) { return s != null && s.indexOf('\0') < 0; }

Try / catch

try { session.connect(authInfo); } catch (AuthenticationException e) { if (e.getMessage().contains("NUL")) sanitizeAndRetry(); }

Prevention

When it happens

Trigger: Sending an AuthResponse byte token containing more than two NUL separators, e.g. a username or password that itself contains a NUL (\0) character, or a malformed third segment.

Common situations: Clients that naively string-concatenate credentials without escaping; corrupted or hand-crafted auth tokens; drivers mis-encoding the PLAIN message; security scanners sending malformed SASL payloads.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/bd3e6171c5d3e0f7. Report an issue: GitHub.