{"record":{"id":"187f55ea18f3dbba","repo":"apple/pkl","slug":"malformedmessageheaderlength","errorCode":"malformedMessageHeaderLength","errorMessage":"malformedMessageHeaderLength","messagePattern":"malformedMessageHeaderLength","errorType":"error_code","errorClass":"DecodeException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/messaging/AbstractMessagePackDecoder.java","lineNumber":60,"sourceCode":"\n  public AbstractMessagePackDecoder(InputStream stream) {\n    this(MessagePack.newDefaultUnpacker(stream));\n  }\n\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);","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/messaging/AbstractMessagePackDecoder.java#L42-L78","documentation":"A MessagePack message frame must decode as an array of exactly 2 elements ([code, body-map]). If the decoded array header reports a different size, the stream is not a valid Pkl messaging stream, so decoding fails with malformedMessageHeaderLength.","triggerScenarios":"unpackArrayHeader() succeeds but returns a size other than 2 while decoding a message header in AbstractMessagePackDecoder.decode.","commonSituations":"Pointing a messaging consumer at a non-Pkl MessagePack stream, truncated/corrupted capture files, or version mismatch where the peer uses a different framing.","solutions":["Verify the input is a Pkl messaging stream with [code, map] framing","Check that producer and consumer use compatible protocol versions","Regenerate or re-export the message stream; discard corrupted data","Validate the file/stream before decoding with a small MessagePack inspection"],"exampleFix":"// before: decoding arbitrary msgpack as messages\ndecoder.decode(unpacker);\n// after: sanity check the stream first\nvar v = new MessagePack.Unpacker(in).unpackValue();\nif (!v.isArrayValue() || v.asArrayValue().size() != 2) throw new IllegalStateException(\"not a pkl message stream\");","handlingStrategy":"validation","validationCode":"var probe = MessagePack.newDefaultUnpacker(bytes).unpackValue(); boolean valid = probe.isArrayValue() && probe.asArrayValue().size() == 2;","typeGuard":null,"tryCatchPattern":"try { return decoder.decode(unpacker); } catch (DecodeException e) { if (String.valueOf(e.getMessage()).contains(\"malformedMessageHeaderLength\")) { throw new IllegalStateException(\"stream is not pkl messaging protocol\", e); } throw e; }","preventionTips":["Only decode streams produced by a pkl evaluator","Verify stream framing before decoding","Check producer/consumer version compatibility"],"tags":["msgpack","decoding","protocol"],"backgroundTag":"unexpected-response-shape","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"}