apple/pkl · error · DecodeException

missingMessageParameter

missingMessageParameter

Error message

missingMessageParameter

What it means

A required parameter key is absent from a decoded message body map. The helper get(map, key) throws DecodeException with code missingMessageParameter naming the missing key; helpers unpackString/unpackBoolean/unpackInt/unpackLong all route through it.

Source

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

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

  protected static @Nullable String unpackStringOrNull(Map<Value, Value> map, String key) {
    var value = getNullable(map, key);
    if (value == null) {
      return null;
    }
    return value.asStringValue().asString();
  }

  protected static <T> @Nullable T unpackStringOrNull(
      Map<Value, Value> map, String key, Function<String, T> mapper) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Ensure the encoder writes every required field for the message type
2. Compare the decoded map keys against the schema and add the missing field on the producer side
3. Use getNullable for genuinely optional fields instead of get
4. Validate incoming maps against the message schema before decoding

Example fix

// before: assumes optional key is present
var msg = unpackString(map, "message");
// after: handle absence explicitly
var msgOrNull = getNullable(map, "message") == null ? "" : unpackString(map, "message");

boolean hasKey = map.containsKey(new ImmutableStringValueImpl("message"));

static boolean hasField(Map<Value,Value> map, String key) { return map.containsKey(new ImmutableStringValueImpl(key)); }

try { var msg = unpackString(map, "message"); } catch (DecodeException e) { if (String.valueOf(e.getMessage()).contains("missingMessageParameter")) { /* supply default or reject producer payload */ } throw e; }

When it happens

Trigger: Decoding a message whose body map lacks a mandatory field (e.g. no 'message' or 'uri' key) that a unpackXxx helper requests.

Common situations: Partial encoder implementations, schema drift between peers, hand-written or trimmed msgpack payloads missing fields.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• malformedMessageHeaderLength
• malformedMessageHeaderException
• malformedMessageHeaderUnrecognizedCode
• unhandledMessageCode
• malformedMessageBody

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