apple/pkl · error · DecodeException

malformedMessageHeaderLength

malformedMessageHeaderLength

Error message

malformedMessageHeaderLength

What it means

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.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/messaging/AbstractMessagePackDecoder.java:60

  public AbstractMessagePackDecoder(InputStream stream) {
    this(MessagePack.newDefaultUnpacker(stream));
  }

  protected abstract @Nullable Message decodeMessage(Type msgType, Map<Value, Value> map)
      throws DecodeException, URISyntaxException;

  @Override
  public @Nullable Message decode() throws IOException, DecodeException {
    if (!unpacker.hasNext()) {
      return null;
    }

    int code;
    try {
      var arraySize = unpacker.unpackArrayHeader();
      if (arraySize != 2) {
        throw new DecodeException(ErrorMessages.create("malformedMessageHeaderLength", arraySize));
      }
      code = unpacker.unpackInt();
    } catch (MessageTypeException e) {
      throw new DecodeException(ErrorMessages.create("malformedMessageHeaderException"), e);
    }

    Type msgType;
    try {
      msgType = Type.fromInt(code);
    } catch (IllegalArgumentException e) {
      throw new DecodeException(
          ErrorMessages.create("malformedMessageHeaderUnrecognizedCode", Integer.toHexString(code)),
          e);
    }

    try {
      var map = unpacker.unpackValue().asMapValue().map();
      var decoded = decodeMessage(msgType, map);

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Verify the input is a Pkl messaging stream with [code, map] framing
2. Check that producer and consumer use compatible protocol versions
3. Regenerate or re-export the message stream; discard corrupted data
4. Validate the file/stream before decoding with a small MessagePack inspection

Example fix

// before: decoding arbitrary msgpack as messages
decoder.decode(unpacker);
// after: sanity check the stream first
var v = new MessagePack.Unpacker(in).unpackValue();
if (!v.isArrayValue() || v.asArrayValue().size() != 2) throw new IllegalStateException("not a pkl message stream");

var probe = MessagePack.newDefaultUnpacker(bytes).unpackValue(); boolean valid = probe.isArrayValue() && probe.asArrayValue().size() == 2;

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; }

When it happens

Trigger: unpackArrayHeader() succeeds but returns a size other than 2 while decoding a message header in AbstractMessagePackDecoder.decode.

Common situations: Pointing a messaging consumer at a non-Pkl MessagePack stream, truncated/corrupted capture files, or version mismatch where the peer uses a different framing.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• unhandledMessageCode
• malformedMessageHeaderException
• malformedMessageHeaderUnrecognizedCode
• malformedMessageBody
• missingMessageParameter

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/187f55ea18f3dbba. Report an issue: GitHub.