apache/rocketmq · error · AuthenticationException

authentication credential length is incorrect, actual length

Error message

authentication credential length is incorrect, actual length={}.

What it means

The 'Credential=<value>' pair was found, but splitting its value on '/' produced zero parts. In Java, String.split on an empty string returns an empty array, so this fires when the credential value is the empty string ('Credential=' with nothing after the '='). The username is taken from credential[0], hence the guard.

Source

Thrown at auth/src/main/java/org/apache/rocketmq/auth/authentication/builder/DefaultAuthenticationContextBuilder.java:78

            }

            String[] result = authorization.split(CommonConstants.SPACE, 2);
            if (result.length != 2) {
                throw new AuthenticationException("authentication header is incorrect.");
            }
            String[] keyValues = result[1].split(CommonConstants.COMMA);
            for (String keyValue : keyValues) {
                String[] kv = keyValue.trim().split(CommonConstants.EQUAL, 2);
                int kvLength = kv.length;
                if (kv.length != 2) {
                    throw new AuthenticationException("authentication keyValues length is incorrect, actual length={}.", kvLength);
                }
                String authItem = kv[0];
                if (CREDENTIAL.equals(authItem)) {
                    String[] credential = kv[1].split(CommonConstants.SLASH);
                    int credentialActualLength = credential.length;
                    if (credentialActualLength == 0) {
                        throw new AuthenticationException("authentication credential length is incorrect, actual length={}.", credentialActualLength);
                    }
                    context.setUsername(credential[0]);
                    continue;
                }
                if (SIGNATURE.equals(authItem)) {
                    context.setSignature(this.hexToBase64(kv[1]));
                }
            }

            context.setContent(datetime.getBytes(StandardCharsets.UTF_8));

            return context;
        } catch (AuthenticationException e) {
            throw e;
        } catch (Throwable e) {
            throw new AuthenticationException("create authentication context error.", e);
        }
    }

View on GitHub (pinned to 293f588571)

Solutions

1. Set a non-empty username/access key in the client credentials so the Credential pair has a value ('Credential=myUser').
2. Check the client-side config (sessionCredentials, ACL config file, environment variables) for an empty accessKey field.
3. Validate the built header client-side before sending: every pair must match '^[^=]+=.+$'.

Example fix

// before
String cred = "Credential=" + username; // username == "" -> 'Credential='

// after
if (username == null || username.isEmpty()) throw new IllegalStateException("accessKey must be set");
String cred = "Credential=" + username;

if (username == null || username.trim().isEmpty()) {
    throw new IllegalStateException("accessKey/username must be non-empty before building the auth header");
}
String credential = "Credential=" + username;

boolean hasValidCredential(String username) { return username != null && !username.trim().isEmpty(); }

catch (AuthenticationException e) { if message contains "credential length" -> check client accessKey config, fail fast (not transient). }

When it happens

Trigger: Header contains 'Credential=' (empty value), e.g. because the username variable was null/empty when the header was built, producing an empty string after the '=' that splits into a zero-length array.

Common situations: Client configured with an empty or unresolvable AK/username (e.g. placeholder not substituted from environment/config); a null username string-concatenated into the header as 'null=' vs empty; misconfigured credentials file.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• username cannot be null.
• datetime is null.
• authentication header is incorrect.
• authentication keyValues length is incorrect, actual length=
• create authentication context error.

AI-assisted analysis of apache/rocketmq@293f588571 (2026-08-14). Data as JSON: /api/errors/f0c301ec5ffc64a5. Report an issue: GitHub.