apple/pkl · error · DecodeException

malformedMessageBody

malformedMessageBody

Error message

malformedMessageBody

What it means

While decoding a message body map, a MessageTypeException (wrong MessagePack type for a field) or URISyntaxException (malformed URI field) occurred; the decoder wraps it as DecodeException with code malformedMessageBody including the message code.

Solutions

1. Inspect the message code in the error and validate that message's fields against the expected schema
2. Regenerate the stream with a matching encoder version
3. Check for text contamination of the binary channel
4. Catch DecodeException around decode and log the raw payload for diagnosis

Example fix

// before
var msg = decoder.decode(unpacker);
// after
try { var msg = decoder.decode(unpacker); }
catch (DecodeException e) { log.warn("bad message body (code={})", e.getMessage(), e); skipFrame(unpacker); }

try { return decoder.decode(unpacker); } catch (DecodeException e) { if (String.valueOf(e.getMessage()).startsWith("malformedMessageBody")) { log.warn("bad body for code {}", codeFromMessage(e)); } throw e; }

When it happens

Trigger: A field inside the message body map has an unexpected type (e.g. string where int expected) or a URI-valued field fails URI parsing.

Common situations: Corrupted or hand-crafted msgpack payloads, encoder/decoder schema drift, streams produced by non-Pkl tools.

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

• Expected structure to have at least slots, found
• malformedMessageHeaderException
• malformedMessageHeaderLength
• malformedMessageHeaderUnrecognizedCode
• missingMessageParameter

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

Appendix: source

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

    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) {
    return map.get(new ImmutableStringValueImpl(key));
  }

  protected static Value get(Map<Value, Value> map, String key) throws DecodeException {
    var value = map.get(new ImmutableStringValueImpl(key));
    if (value == null) {
      throw new DecodeException(ErrorMessages.create("missingMessageParameter", key));
    }
    return value;
  }

  protected static String unpackString(Map<Value, Value> map, String key) throws DecodeException {
    return get(map, key).asStringValue().asString();
  }

View on GitHub (pinned to f3efcbfc9b)