{"record":{"id":"e8a0d7697e861de3","repo":"apple/pkl","slug":"formatexception-key-array-ret-getclass","errorCode":null,"errorMessage":"FormatException(key, \"array\", ret.getClass())","messagePattern":"FormatException\\(key, \"array\", ret\\.getClass\\(\\)\\)","errorType":"exception","errorClass":"FormatException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/util/json/Json.java","lineNumber":309,"sourceCode":"\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 {\n        return Version.parse(versionStr);\n      } catch (IllegalArgumentException e) {\n        throw new MappingException(key, e);\n      }\n    }\n\n    public URI getURI(String key) throws JsonParseException {\n      var result = getURIOrNull(key);\n      if (result == null) {\n        throw new MissingFieldException(this, key);\n      }","sourceCodeStart":291,"sourceCodeEnd":327,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/util/json/Json.java#L291-L327","documentation":"Thrown by JsObject.getArray(String) when the key is present but the value is not a JSON array (e.g. a string, number, or object). The FormatException names the key, the expected type 'array', and the actual value class.","triggerScenarios":"Calling getArray(key) where the JSON value under key is a scalar or object, e.g. {\"exports\": \"all\"} instead of {\"exports\": [\"all\"]}.","commonSituations":"Schema change turned an array field into a scalar for single-element cases; producer bug; hand-edited JSON dropping the brackets.","solutions":["Inspect the value's real type with get(key).getClass()","Use the appropriate getter for the actual type or normalize single values into a list","Fix the producer to emit a JSON array","Pre-validate with instanceof before calling"],"exampleFix":"// before: {\"exports\": \"all\"} -> obj.getArray(\"exports\") throws\n// after: {\"exports\": [\"all\"]}","handlingStrategy":"type-guard","validationCode":"Object v = obj.get(\"exports\");\nif (!(v instanceof JsArray)) throw new IllegalStateException(\"field 'exports' must be a JSON array, got \" + (v == null ? \"null\" : v.getClass().getSimpleName()));","typeGuard":"boolean isArrayField(JsObject o, String k) { return o.get(k) instanceof JsArray; }","tryCatchPattern":"try { JsArray a = obj.getArray(\"exports\"); } catch (JsonParseException e) { /* normalize scalar to single-element list */ }","preventionTips":["Ensure list values are wrapped in [ ] even for a single element","Inspect the parsed type before calling getArray","Validate the document schema before reading"],"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"}