apple/pkl · error · MappingException

MappingException(key, e)

Error message

MappingException(key, e)

What it means

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.

Solutions

1. Print the raw string via getString(key) and check it against the expected version format
2. Correct the version string in the JSON document
3. If the value may be non-numeric, read it with getStringOrNull and validate before Version.parse
4. Catch MappingException and fall back to a default version or skip the entry

Example fix

// before: {"version": "latest"} -> obj.getVersion("version") throws MappingException
// after: {"version": "1.2.3"}
// or:
String s = obj.getStringOrNull("version");
Version v = s != null && s.matches("\\d+(\\.\\d+)*.*") ? obj.getVersion("version") : null;

String s = obj.getStringOrNull("version");
if (s != null && !s.matches("\\d+(\\.\\d+){0,2}([-+].*)?")) throw new IllegalStateException("'version' is not a valid version string: " + s);

boolean isVersionLike(@Nullable String s) { return s != null && s.matches("\\d+(\\.\\d+){0,2}([-+].*)?"); }

try { Version v = obj.getVersion("version"); } catch (MappingException e) { /* log key and cause, fall back to default version */ }

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• array
• Cannot parse ` ` as number.
• cannotRenderValue
• '" + ch + "'
• Could not read annotation. Invalid object:

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

Appendix: source

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

    }

    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 {
        return Version.parse(versionStr);
      } catch (IllegalArgumentException e) {
        throw new MappingException(key, e);
      }
    }

    public URI getURI(String key) throws JsonParseException {
      var result = getURIOrNull(key);
      if (result == null) {
        throw new MissingFieldException(this, key);
      }
      return result;
    }

    public @Nullable URI getURIOrNull(String key) throws JsonParseException {
      var uriStr = getStringOrNull(key);
      if (uriStr == null) {
        return null;
      }
      try {
        return new URI(uriStr);

View on GitHub (pinned to f3efcbfc9b)