apple/pkl · error · MappingException

MissingFieldException(this, key)

Error message

MissingFieldException(this, key)

What it means

JsObject.get(key, mapper) throws MissingFieldException when the key is absent from the JSON object (or maps to JSON null), because the mapper result would be indistinguishable from null. Unlike getNullable, get treats a missing key as a hard error.

Solutions

1. Use getNullable(key, mapper) when the field is genuinely optional.
2. Check key presence first (containsKey or inspecting the map) before calling get.
3. Fix the producer/schema so the field is always emitted.

Example fix

// before
String id = obj.get("id", JsString::value);
// after
String id = obj.getNullable("id", JsString::value);
if (id == null) { /* handle missing */ }

if (obj.getNullable(key, Function.identity()) == null) { /* default or fail fast with a clear message */ }

String id = obj.getNullable("id", JsString::value);
if (id == null) throw new IllegalStateException("missing required field 'id' in payload");

try {
  String id = obj.get("id", JsString::value);
} catch (Json.MissingFieldException e) {
  // supply default or report missing field
}

When it happens

Trigger: Calling get(key, mapper) or getNullable on a JSON object where the key does not exist, e.g. parsing a response and reading obj.get("id", ...) when the server omitted "id".

Common situations: Optional fields in API responses absent in error/degraded responses; schema drift after API version changes; fields only present in newer payload versions.

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

• FormatException(key, "boolean", ret.getClass())
• jsonParseError
• object
• value
• array

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

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/util/json/Json.java:239

    private final Map<String, @Nullable Object> delegate;

    public JsObject() {
      this.delegate = new HashMap<>();
    }

    public JsObject(int size) {
      this.delegate = new HashMap<>(size);
    }

    public <T> T get(String key, Mapper<T> mapper) throws JsonParseException {
      var ret = get(key);
      if (ret == null) {
        throw new MissingFieldException(this, key);
      }
      try {
        return mapper.apply(ret);
      } catch (Exception e) {
        throw new MappingException(key, e);
      }
    }

    public <T> @Nullable T getNullable(String key, Mapper<T> mapper) throws JsonParseException {
      var ret = get(key);
      if (ret == null) {
        return null;
      }
      return get(key, mapper);
    }

    public boolean getBoolean(String key) throws JsonParseException {
      var ret = get(key);
      if (ret == null) {
        throw new MissingFieldException(this, key);
      }
      if (!(ret instanceof Boolean b)) {
        throw new FormatException(key, "boolean", ret.getClass());

View on GitHub (pinned to f3efcbfc9b)