apache/cassandra · error · AuthenticationException

Required key '%s' is missing

Error message

Required key '%s' is missing

What it means

Thrown by PasswordAuthenticator.legacyAuthenticate when the credentials map supplied (via the legacy Thrift-style authentication API) lacks the 'username' key. The authenticator requires both USERNAME_KEY and PASSWORD_KEY entries to perform authentication.

Source

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

    public void validateConfiguration() throws ConfigurationException
    {
    }

    public void setup()
    {
        String query = String.format("SELECT %s FROM %s.%s WHERE role = ?",
                                     SALTED_HASH,
                                     SchemaConstants.AUTH_KEYSPACE_NAME,
                                     AuthKeyspace.ROLES);
        authenticateStatement = prepare(query);
    }

    public AuthenticatedUser legacyAuthenticate(Map<String, String> credentials) throws AuthenticationException
    {
        String username = credentials.get(USERNAME_KEY);
        if (username == null)
            throw new AuthenticationException(String.format("Required key '%s' is missing", USERNAME_KEY));

        String password = credentials.get(PASSWORD_KEY);
        if (password == null)
            throw new AuthenticationException(String.format("Required key '%s' is missing for provided username %s", PASSWORD_KEY, username));

        return authenticate(username, password);
    }

    public SaslNegotiator newSaslNegotiator(InetAddress clientAddress)
    {
        return new PlainTextSaslAuthenticator();
    }

    @Override
    public Set<AuthenticationMode> getSupportedAuthenticationModes()
    {
        return AUTHENTICATION_MODES;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Include the 'username' key in the credentials map
2. Verify exact key names: 'username' and 'password' (case-sensitive)
3. Use a modern driver with SASL/plain authentication instead of the legacy map API

Example fix

// before
Map<String,String> creds = Map.of("password", "s3cret");
// after
Map<String,String> creds = Map.of("username", "appuser", "password", "s3cret");

// validate credentials map before calling
if (creds.get("username") == null) throw new IllegalArgumentException("username required");
authenticator.legacyAuthenticate(creds);

try { authenticator.legacyAuthenticate(creds); }
catch (AuthenticationException e) { /* report missing 'username' key to caller */ }

When it happens

Trigger: Calling legacyAuthenticate(Map<String,String> credentials) with a map missing the 'username' key; client sending only a password, or using wrong key names in the credentials payload.

Common situations: Legacy client drivers or custom auth shims passing credentials under different key names (e.g. 'user' instead of 'username'); programmatic use of the authenticator API.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Required key '%s' is missing for provided username %s
• Provided username %s and/or password are incorrect
• Unable to perform authentication:
• SASL negotiation not complete
• Credential format error: username or password is empty or co

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