{"record":{"id":"852d84a62b7f9294","repo":"apache/rocketmq","slug":"create-authentication-context-error","errorCode":null,"errorMessage":"create authentication context error.","messagePattern":"create authentication context error\\.","errorType":"exception","errorClass":"AuthenticationException","httpStatus":null,"severity":"error","filePath":"auth/src/main/java/org/apache/rocketmq/auth/authentication/builder/DefaultAuthenticationContextBuilder.java","lineNumber":94,"sourceCode":"                    int credentialActualLength = credential.length;\n                    if (credentialActualLength == 0) {\n                        throw new AuthenticationException(\"authentication credential length is incorrect, actual length={}.\", credentialActualLength);\n                    }\n                    context.setUsername(credential[0]);\n                    continue;\n                }\n                if (SIGNATURE.equals(authItem)) {\n                    context.setSignature(this.hexToBase64(kv[1]));\n                }\n            }\n\n            context.setContent(datetime.getBytes(StandardCharsets.UTF_8));\n\n            return context;\n        } catch (AuthenticationException e) {\n            throw e;\n        } catch (Throwable e) {\n            throw new AuthenticationException(\"create authentication context error.\", e);\n        }\n    }\n\n    @Override\n    public DefaultAuthenticationContext build(ChannelHandlerContext context, RemotingCommand request) {\n        HashMap<String, String> fields = request.getExtFields();\n        DefaultAuthenticationContext result = new DefaultAuthenticationContext();\n        result.setChannelId(context.channel().id().asLongText());\n        result.setRpcCode(String.valueOf(request.getCode()));\n        if (MapUtils.isEmpty(fields)) {\n            return result;\n        }\n        if (!fields.containsKey(SessionCredentials.ACCESS_KEY)) {\n            return result;\n        }\n        result.setUsername(fields.get(SessionCredentials.ACCESS_KEY));\n        result.setSignature(fields.get(SessionCredentials.SIGNATURE));\n        // Content","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/auth/src/main/java/org/apache/rocketmq/auth/authentication/builder/DefaultAuthenticationContextBuilder.java#L76-L112","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the cause of the thrown AuthenticationException (getCause()) to identify the real failure - typically an IllegalArgumentException from the signature decoding.","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.","Round-trip test the header with DefaultAuthenticationContextBuilder on the client side before sending."],"exampleFix":"// before\nbyte[] sig = mac.doFinal(datetime.getBytes());\nString signature = Base64.getEncoder().encodeToString(sig); // server expects hex\n\n// after\nbyte[] sig = mac.doFinal(datetime.getBytes());\nString signature = Hex.encodeHexString(sig); // hex, matching org.apache.rocketmq.auth.authentication.model.AclSigner expectations","handlingStrategy":"try-catch","validationCode":"// Client-side pre-flight: round-trip the header through the same conversion the server does\ntry {\n    // simulate server: signature must be valid hex\n    javax.xml.bind.DatatypeConverter.parseHexBinary(signature);\n} catch (IllegalArgumentException e) {\n    throw new IllegalStateException(\"signature must be hex-encoded\");\n}","typeGuard":"boolean isHex(String s) { return s != null && s.matches(\"[0-9a-fA-F]+\"); }","tryCatchPattern":"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. }","preventionTips":["Always inspect getCause() for wrapped context-build errors","Mirror AclSigner's HMAC-SHA256 + hex encoding exactly in custom clients"],"tags":["rocketmq","authentication","signature","encoding"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}