apple/pkl · error · DecodeException

malformedMessageHeaderUnrecognizedCode

malformedMessageHeaderUnrecognizedCode

Error message

malformedMessageHeaderUnrecognizedCode

What it means

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.

Source

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

      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);
      if (decoded != null) {
        return decoded;
      }
      throw new DecodeException(
          ErrorMessages.create("unhandledMessageCode", Integer.toHexString(code)));
    } catch (MessageTypeException | URISyntaxException e) {
      throw new DecodeException(ErrorMessages.create("malformedMessageBody", code), e);
    }
  }

  protected static @Nullable Value getNullable(Map<Value, Value> map, String key) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Align decoder and encoder versions so the message code set matches
2. Identify the reported hex code and map it to the peer's protocol
3. Re-encode the stream with a compatible version before decoding
4. Reject/handle unknown codes explicitly in custom decoders

Example fix

// before: strict decode fails on new codes
var decoded = decoder.decode(unpacker);
// after: check version compatibility first
if (!isSupportedPeerVersion(peerVersion)) { throw new IllegalStateException("peer protocol too new; upgrade pkl"); }

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

When it happens

Trigger: 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).

Common situations: 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.

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

• malformedMessageHeaderLength
• malformedMessageHeaderException
• unhandledMessageCode
• malformedMessageBody
• missingMessageParameter

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