apple/pkl · error · FormatException

FormatException(key, "object", ret.getClass())

Error message

FormatException(key, "object", ret.getClass())

What it means

Thrown by JsObject.getObject(String) when the key exists but its value parsed to something other than a JSON object (Integer, String, JsArray, etc.). The FormatException records the key, expected type 'object', and the actual value class.

Source

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

    public @Nullable String getStringOrNull(String key) throws JsonParseException {
      var ret = get(key);
      if (ret == null) {
        return null;
      }
      if (!(ret instanceof String string)) {
        throw new FormatException(key, "string", ret.getClass());
      }
      return string;
    }

    public JsObject getObject(String key) throws JsonParseException {
      var ret = get(key);
      if (ret == null) {
        throw new MissingFieldException(this, key);
      }
      if (!(ret instanceof JsObject jsObject)) {
        throw new FormatException(key, "object", ret.getClass());
      }
      return jsObject;
    }

    public JsArray getArray(String key) throws JsonParseException {
      var ret = get(key);
      if (ret == null) {
        throw new MissingFieldException(this, key);
      }
      if (!(ret instanceof JsArray jsArray)) {
        throw new FormatException(key, "array", ret.getClass());
      }
      return jsArray;
    }

    public Version getVersion(String key) throws JsonParseException {
      var versionStr = getString(key);
      try {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Check the actual parsed type via get(key).getClass()
2. Read the field with the getter matching the real type, or adapt the parsing code
3. Fix the producer so the field is emitted as a JSON object
4. Validate the shape with instanceof before calling getObject

Example fix

// before: {"options": ["a"]} -> obj.getObject("options") throws
// after: {"options": {"a": 1}}

Object v = obj.get("options");
if (!(v instanceof JsObject)) throw new IllegalStateException("field 'options' must be a JSON object, got " + (v == null ? "null" : v.getClass().getSimpleName()));

boolean isObjectField(JsObject o, String k) { return o.get(k) instanceof JsObject; }

try { JsObject o = obj.getObject("options"); } catch (JsonParseException e) { /* handle shape mismatch */ }

When it happens

Trigger: Calling getObject(key) where the JSON value under key is a scalar or array, e.g. {"options": [1,2]} or {"options": "none"}.

Common situations: A field that used to be a nested object became a flat string/array in a newer document format; producer bug serializing the wrong shape; hand-edited JSON.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• double
• string
• FormatException(key, "integer", ret.getClass())
• FormatException(key, "string", ret.getClass())
• FormatException(key, "array", ret.getClass())

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