{"record":{"id":"22e96082ed94d4d1","repo":"apple/pkl","slug":"mappingexception-key-e","errorCode":null,"errorMessage":"MappingException(key, e)","messagePattern":"MappingException\\(key, e\\)","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/util/json/Json.java","lineNumber":319,"sourceCode":"    }\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      }\n      return result;\n    }\n\n    public @Nullable URI getURIOrNull(String key) throws JsonParseException {\n      var uriStr = getStringOrNull(key);\n      if (uriStr == null) {\n        return null;\n      }\n      try {\n        return new URI(uriStr);","sourceCodeStart":301,"sourceCodeEnd":337,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/util/json/Json.java#L301-L337","documentation":"Thrown by JsObject.getVersion(String) when the string value under the key cannot be parsed by Version.parse as a valid version. The underlying IllegalArgumentException is rewrapped in a MappingException that names the key, so the failure is attributed to the JSON field rather than the parsing call site.","triggerScenarios":"Calling getVersion(key) where the field is a string not matching the expected version grammar (e.g. \"latest\", \"1.0\", \"v2-alpha...\", or an empty string).","commonSituations":"A dependency record stores a placeholder or branch name instead of a semantic version; a producer writes a non-SEMVER format; hand-edited metadata with a typo.","solutions":["Print the raw string via getString(key) and check it against the expected version format","Correct the version string in the JSON document","If the value may be non-numeric, read it with getStringOrNull and validate before Version.parse","Catch MappingException and fall back to a default version or skip the entry"],"exampleFix":"// before: {\"version\": \"latest\"} -> obj.getVersion(\"version\") throws MappingException\n// after: {\"version\": \"1.2.3\"}\n// or:\nString s = obj.getStringOrNull(\"version\");\nVersion v = s != null && s.matches(\"\\\\d+(\\\\.\\\\d+)*.*\") ? obj.getVersion(\"version\") : null;","handlingStrategy":"validation","validationCode":"String s = obj.getStringOrNull(\"version\");\nif (s != null && !s.matches(\"\\\\d+(\\\\.\\\\d+){0,2}([-+].*)?\")) throw new IllegalStateException(\"'version' is not a valid version string: \" + s);","typeGuard":"boolean isVersionLike(@Nullable String s) { return s != null && s.matches(\"\\\\d+(\\\\.\\\\d+){0,2}([-+].*)?\"); }","tryCatchPattern":"try { Version v = obj.getVersion(\"version\"); } catch (MappingException e) { /* log key and cause, fall back to default version */ }","preventionTips":["Validate version strings against the expected grammar before parsing","Reject placeholder values ('latest', branch names) at the producer","Keep a canonical version format across emitting tools"],"tags":["json","version-parsing","pkl"],"backgroundTag":"invalid-argument-format","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}