{"record":{"id":"35ca9ce3fa3e3b09","repo":"apple/pkl","slug":"formatexception-key-object-ret-getclass","errorCode":null,"errorMessage":"FormatException(key, \"object\", ret.getClass())","messagePattern":"FormatException\\(key, \"object\", ret\\.getClass\\(\\)\\)","errorType":"exception","errorClass":"FormatException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/util/json/Json.java","lineNumber":298,"sourceCode":"\n    public @Nullable String getStringOrNull(String key) throws JsonParseException {\n      var ret = get(key);\n      if (ret == null) {\n        return null;\n      }\n      if (!(ret instanceof String string)) {\n        throw new FormatException(key, \"string\", ret.getClass());\n      }\n      return string;\n    }\n\n    public JsObject getObject(String key) throws JsonParseException {\n      var ret = get(key);\n      if (ret == null) {\n        throw new MissingFieldException(this, key);\n      }\n      if (!(ret instanceof JsObject jsObject)) {\n        throw new FormatException(key, \"object\", ret.getClass());\n      }\n      return jsObject;\n    }\n\n    public JsArray getArray(String key) throws JsonParseException {\n      var ret = get(key);\n      if (ret == null) {\n        throw new MissingFieldException(this, key);\n      }\n      if (!(ret instanceof JsArray jsArray)) {\n        throw new FormatException(key, \"array\", ret.getClass());\n      }\n      return jsArray;\n    }\n\n    public Version getVersion(String key) throws JsonParseException {\n      var versionStr = getString(key);\n      try {","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/util/json/Json.java#L280-L316","documentation":"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.","triggerScenarios":"Calling getObject(key) where the JSON value under key is a scalar or array, e.g. {\"options\": [1,2]} or {\"options\": \"none\"}.","commonSituations":"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.","solutions":["Check the actual parsed type via get(key).getClass()","Read the field with the getter matching the real type, or adapt the parsing code","Fix the producer so the field is emitted as a JSON object","Validate the shape with instanceof before calling getObject"],"exampleFix":"// before: {\"options\": [\"a\"]} -> obj.getObject(\"options\") throws\n// after: {\"options\": {\"a\": 1}}","handlingStrategy":"type-guard","validationCode":"Object v = obj.get(\"options\");\nif (!(v instanceof JsObject)) throw new IllegalStateException(\"field 'options' must be a JSON object, got \" + (v == null ? \"null\" : v.getClass().getSimpleName()));","typeGuard":"boolean isObjectField(JsObject o, String k) { return o.get(k) instanceof JsObject; }","tryCatchPattern":"try { JsObject o = obj.getObject(\"options\"); } catch (JsonParseException e) { /* handle shape mismatch */ }","preventionTips":["Confirm nested values are { } not [ ] or scalars in the JSON source","Inspect parsed types before narrowing","Validate document shape against a schema"],"tags":["json","type-mismatch","pkl"],"backgroundTag":"type-mismatch","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}