{"record":{"id":"e5036d9bed92ece5","repo":"apple/pkl","slug":"malformedmessageheaderunrecognizedcode","errorCode":"malformedMessageHeaderUnrecognizedCode","errorMessage":"malformedMessageHeaderUnrecognizedCode","messagePattern":"malformedMessageHeaderUnrecognizedCode","errorType":"error_code","errorClass":"DecodeException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/messaging/AbstractMessagePackDecoder.java","lineNumber":71,"sourceCode":"      return null;\n    }\n\n    int code;\n    try {\n      var arraySize = unpacker.unpackArrayHeader();\n      if (arraySize != 2) {\n        throw new DecodeException(ErrorMessages.create(\"malformedMessageHeaderLength\", arraySize));\n      }\n      code = unpacker.unpackInt();\n    } catch (MessageTypeException e) {\n      throw new DecodeException(ErrorMessages.create(\"malformedMessageHeaderException\"), e);\n    }\n\n    Type msgType;\n    try {\n      msgType = Type.fromInt(code);\n    } catch (IllegalArgumentException e) {\n      throw new DecodeException(\n          ErrorMessages.create(\"malformedMessageHeaderUnrecognizedCode\", Integer.toHexString(code)),\n          e);\n    }\n\n    try {\n      var map = unpacker.unpackValue().asMapValue().map();\n      var decoded = decodeMessage(msgType, map);\n      if (decoded != null) {\n        return decoded;\n      }\n      throw new DecodeException(\n          ErrorMessages.create(\"unhandledMessageCode\", Integer.toHexString(code)));\n    } catch (MessageTypeException | URISyntaxException e) {\n      throw new DecodeException(ErrorMessages.create(\"malformedMessageBody\", code), e);\n    }\n  }\n\n  protected static @Nullable Value getNullable(Map<Value, Value> map, String key) {","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/messaging/AbstractMessagePackDecoder.java#L53-L89","documentation":"The integer message code in the frame header is not a known message Type. Type.fromInt(code) throws IllegalArgumentException, which is wrapped as DecodeException with code malformedMessageHeaderUnrecognizedCode along with the hex code.","triggerScenarios":"Decoding a frame whose first array element is an integer outside the set of defined message type codes (e.g. produced by a newer/older protocol version).","commonSituations":"Protocol version mismatch between encoder and decoder; a peer built from a different pkl version introducing new message codes; corrupted data where an integer got misread.","solutions":["Align decoder and encoder versions so the message code set matches","Identify the reported hex code and map it to the peer's protocol","Re-encode the stream with a compatible version before decoding","Reject/handle unknown codes explicitly in custom decoders"],"exampleFix":"// before: strict decode fails on new codes\nvar decoded = decoder.decode(unpacker);\n// after: check version compatibility first\nif (!isSupportedPeerVersion(peerVersion)) { throw new IllegalStateException(\"peer protocol too new; upgrade pkl\"); }","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { return decoder.decode(unpacker); } catch (DecodeException e) { if (String.valueOf(e.getMessage()).contains(\"malformedMessageHeaderUnrecognizedCode\")) { /* upgrade pkl or ask peer for its protocol version */ } throw e; }","preventionTips":["Pin matching pkl versions on producer and consumer","Handle unknown message codes gracefully in custom decoders","Log hex codes to identify protocol drift early"],"tags":["msgpack","decoding","protocol-version"],"backgroundTag":"unsupported-enum-value","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}