{"record":{"id":"6fb19c8e48564255","repo":"apple/pkl","slug":"malformedmessageheaderexception","errorCode":"malformedMessageHeaderException","errorMessage":"malformedMessageHeaderException","messagePattern":"malformedMessageHeaderException","errorType":"error_code","errorClass":"DecodeException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/messaging/AbstractMessagePackDecoder.java","lineNumber":64,"sourceCode":"\n  protected abstract @Nullable Message decodeMessage(Type msgType, Map<Value, Value> map)\n      throws DecodeException, URISyntaxException;\n\n  @Override\n  public @Nullable Message decode() throws IOException, DecodeException {\n    if (!unpacker.hasNext()) {\n      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(","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/messaging/AbstractMessagePackDecoder.java#L46-L82","documentation":"The first element of a message frame must be an integer message code. If unpackInt() hits a value of a different MessagePack type, a MessageTypeException is wrapped as DecodeException with code malformedMessageHeaderException.","triggerScenarios":"Decoding a frame whose array element 0 is a string, nil, map, etc. instead of an integer code.","commonSituations":"Corrupted or hand-edited message files, wrong stream interleaving (e.g. reading stdout text into the msgpack channel), or peer encoding with an incompatible schema.","solutions":["Confirm the peer writes [int, map] frames with an integer first element","Check you are reading from the binary channel, not a text/log stream","Re-capture or regenerate the stream; inspect bytes at the failure offset","Upgrade the peer library so both sides use the same message format"],"exampleFix":"// before: trusting the header code\nvar code = unpacker.unpackInt();\n// after: guard against type errors upstream\nif (!nextValueIsInteger(unpacker)) throw new IllegalStateException(\"expected integer message code, got \" + describeNext(unpacker));","handlingStrategy":"validation","validationCode":"// peek: first frame element must be an integer code\nboolean headerIsInt = peekNextTypeIsInteger(unpacker);","typeGuard":null,"tryCatchPattern":"try { return decoder.decode(unpacker); } catch (DecodeException e) { if (String.valueOf(e.getMessage()).contains(\"malformedMessageHeaderException\")) { log.error(\"corrupt msgpack header at offset {}\", bytesRead); } throw e; }","preventionTips":["Keep binary msgpack channels separate from text/logging output","Checksum or validate captured streams","Use matching library versions on both ends"],"tags":["msgpack","decoding","type-mismatch"],"backgroundTag":"protobuf-unmarshal-failed","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"}