apache/rocketmq · error · AuthenticationException

create authentication context error.

Error message

create authentication context error.

What it means

Catch-all wrapper: any Throwable other than an AuthenticationException escaping the gRPC context-building logic is rethrown as AuthenticationException('create authentication context error.') with the original as cause. The most common underlying cause is hexToBase64(kv[1]) failing (e.g. IllegalArgumentException from decoding a signature that is not valid hex/base64), but NPEs or charset issues also land here.

Source

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

                    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);
        }
    }

    @Override
    public DefaultAuthenticationContext build(ChannelHandlerContext context, RemotingCommand request) {
        HashMap<String, String> fields = request.getExtFields();
        DefaultAuthenticationContext result = new DefaultAuthenticationContext();
        result.setChannelId(context.channel().id().asLongText());
        result.setRpcCode(String.valueOf(request.getCode()));
        if (MapUtils.isEmpty(fields)) {
            return result;
        }
        if (!fields.containsKey(SessionCredentials.ACCESS_KEY)) {
            return result;
        }
        result.setUsername(fields.get(SessionCredentials.ACCESS_KEY));
        result.setSignature(fields.get(SessionCredentials.SIGNATURE));
        // Content

View on GitHub (pinned to 293f588571)

Solutions

1. Inspect the cause of the thrown AuthenticationException (getCause()) to identify the real failure - typically an IllegalArgumentException from the signature decoding.
2. Make the client sign exactly like AclSigner.calSignature: HMAC-SHA256 over the datetime string, then hex-encode the result, so the server's hexToBase64 step succeeds.
3. Round-trip test the header with DefaultAuthenticationContextBuilder on the client side before sending.

Example fix

// before
byte[] sig = mac.doFinal(datetime.getBytes());
String signature = Base64.getEncoder().encodeToString(sig); // server expects hex

// after
byte[] sig = mac.doFinal(datetime.getBytes());
String signature = Hex.encodeHexString(sig); // hex, matching org.apache.rocketmq.auth.authentication.model.AclSigner expectations

// Client-side pre-flight: round-trip the header through the same conversion the server does
try {
    // simulate server: signature must be valid hex
    javax.xml.bind.DatatypeConverter.parseHexBinary(signature);
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("signature must be hex-encoded");
}

boolean isHex(String s) { return s != null && s.matches("[0-9a-fA-F]+"); }

catch (AuthenticationException e) { Throwable cause = e.getCause(); log cause first - the wrapper message hides the real failure; fix encoding/config per cause; never blind-retry. }

When it happens

Trigger: Authorization header whose Signature value is not valid hexadecimal, causing the hex-to-Base64 conversion inside build(Metadata, GeneratedMessageV3) to throw; any unexpected runtime exception during parsing of the header or datetime bytes.

Common situations: Client sends a raw base64 or arbitrary string signature where the server expects hex; signature generated with a different algorithm/encoding than AclSigner produces; truncated signatures truncated by header size limits.

Understand the failure class

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

Related errors

• check signature failed.
• datetime is null.
• authentication header is incorrect.
• authentication keyValues length is incorrect, actual length=
• authentication credential length is incorrect, actual length

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