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.

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)

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

• malformedMessageHeaderLength
• malformedMessageHeaderException
• malformedMessageHeaderUnrecognizedCode
• unhandledMessageCode
• missingMessageParameter

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