{"record":{"id":"c6e2267a86dc696a","repo":"dianping/cat","slug":"unrecognized-version-s-for-binary-message-codec","errorCode":null,"errorMessage":"Unrecognized version(%s) for binary message codec!","messagePattern":"Unrecognized version\\((.+?)\\) for binary message codec!","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"cat-core/src/main/java/com/dianping/cat/message/codec/NativeMessageCodec.java","lineNumber":177,"sourceCode":"\t\tHEADER {\n\t\t\t@Override\n\t\t\tprotected Message decode(Context ctx, ByteBuf buf) {\n\t\t\t\tMessageTree tree = ctx.getMessageTree();\n\t\t\t\tString version = ctx.getVersion(buf);\n\n\t\t\t\tif (ID.equals(version)) {\n\t\t\t\t\ttree.setDomain(ctx.readString(buf));\n\t\t\t\t\ttree.setHostName(ctx.readString(buf));\n\t\t\t\t\ttree.setIpAddress(ctx.readString(buf));\n\t\t\t\t\ttree.setThreadGroupName(ctx.readString(buf));\n\t\t\t\t\ttree.setThreadId(ctx.readString(buf));\n\t\t\t\t\ttree.setThreadName(ctx.readString(buf));\n\t\t\t\t\ttree.setMessageId(ctx.readString(buf));\n\t\t\t\t\ttree.setParentMessageId(ctx.readString(buf));\n\t\t\t\t\ttree.setRootMessageId(ctx.readString(buf));\n\t\t\t\t\ttree.setSessionToken(ctx.readString(buf));\n\t\t\t\t} else {\n\t\t\t\t\tthrow new RuntimeException(String.format(\"Unrecognized version(%s) for binary message codec!\", version));\n\t\t\t\t}\n\n\t\t\t\treturn null;\n\t\t\t}\n\n\t\t\t@Override\n\t\t\tprotected void encode(Context ctx, ByteBuf buf, Message msg) {\n\t\t\t\tMessageTree tree = ctx.getMessageTree();\n\n\t\t\t\tctx.writeVersion(buf, ID);\n\t\t\t\tctx.writeString(buf, tree.getDomain());\n\t\t\t\tctx.writeString(buf, tree.getHostName());\n\t\t\t\tctx.writeString(buf, tree.getIpAddress());\n\t\t\t\tctx.writeString(buf, tree.getThreadGroupName());\n\t\t\t\tctx.writeString(buf, tree.getThreadId());\n\t\t\t\tctx.writeString(buf, tree.getThreadName());\n\t\t\t\tctx.writeString(buf, tree.getMessageId());\n\t\t\t\tctx.writeString(buf, tree.getParentMessageId());","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/dianping/cat/blob/e815e74d4c2dd74edac831241f1253fcc7d25381/cat-core/src/main/java/com/dianping/cat/message/codec/NativeMessageCodec.java#L159-L195","documentation":"The HEADER codec of NativeMessageCodec reads a version string at the start of every NT1 binary tree and throws RuntimeException(\"Unrecognized version(%s) for binary message codec!\") unless it equals the expected ID constant. Any client emitting a different header string (older/newer protocol revision) is rejected before any field decoding.","triggerScenarios":"A cat-client with a different binary header version sends trees to a cat-core whose NativeMessageCodec.ID does not match; or the buffer is misframed so the 'version' read picks up non-header bytes.","commonSituations":"Mixed-version CAT clusters (old client, new server or vice versa) during rolling upgrades; hot-redeploy of one side only; framed-pipeline bugs that shift the reader index before decode.","solutions":["Capture the version string from the exception — it shows exactly what the peer sent.","Align client and server versions (upgrade/downgrade so both use the same NT1 header contract).","During rolling upgrades, keep protocol-compatible versions overlapping or drain old clients first.","Verify Netty framing so the version bytes are read from offset 0 of the message."],"exampleFix":"# before\nclient 3.1.x (header v1) -> server 2.x (expects older ID): throws\n\n# after\nupgrade all cat-clients to match cat-core version, e.g. both on 3.1.x: NT1 header accepted","handlingStrategy":"validation","validationCode":"String tag = buf.toString(0, 3, StandardCharsets.US_ASCII);\nif (!\"NT1\".equals(tag)) reject(\"expected NT1 header, got \" + tag);","typeGuard":null,"tryCatchPattern":"catch (RuntimeException e) { if (e.getMessage().contains(\"Unrecognized version\")) { log peer version from message; isolate/upgrade node; } else throw e; }","preventionTips":["Keep the whole CAT fleet on one version during rolling upgrades.","Log the reported version string to identify the offending client quickly."],"tags":["protocol","versioning","binary-decoding","upgrade"],"backgroundTag":null,"analyzedSha":"e815e74d4c2dd74edac831241f1253fcc7d25381","analyzedAt":"2026-08-14T14:22:34.512Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}