apple/pkl · error · PklException

Could not read annotation. Invalid object:

Error message

Could not read annotation. Invalid object: 

What it means

PklException("Could not read annotation. Invalid object: " + obj) is thrown by DependencyMetadata.parseAnnotations when an element inside the annotations array parses to something that is not a PObject (annotation objects must be JSON objects). The message includes the parsed value for diagnosis. It signals a structurally invalid annotation entry in package metadata.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/packages/DependencyMetadata.java:175

                var checksums = obj.get("checksums", DependencyMetadata::parseChecksums);
                var packageUri = obj.get("uri", PackageUtils::parsePackageUriWithoutChecksums);
                return new RemoteDependency(packageUri, checksums);
              });
      ret.put(key, remoteDependency);
    }
    return ret;
  }

  private static List<PObject> parseAnnotations(Object ann)
      throws JsonParseException, URISyntaxException {
    if (!(ann instanceof JsArray arr)) {
      throw new FormatException("array", ann.getClass());
    }
    var annotations = new ArrayList<PObject>(arr.size());
    for (var annotation : arr) {
      var obj = parsePObject(annotation);
      if (!(obj instanceof PObject pObject)) {
        throw new PklException("Could not read annotation. Invalid object: " + obj);
      }
      annotations.add(pObject);
    }
    return annotations;
  }

  private static Object parsePObject(@Nullable Object obj)
      throws JsonParseException, URISyntaxException {
    if (obj == null) {
      return PNull.getInstance();
    } else if (obj instanceof String string) {
      return string;
    } else if (obj instanceof Boolean bool) {
      return bool;
    } else if (obj instanceof Integer integer) {
      return integer.longValue();
    } else if (obj instanceof Long aLong) {
      return aLong;

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Make every element of the `annotations` array a JSON object.
2. Regenerate the package metadata with `pkl project package`.
3. Inspect the value printed in the message to find which entry is malformed.
4. Re-publish/re-download the package if the artifact itself is bad.

Example fix

// before
{"annotations": ["mit-license"]}
// after
{"annotations": [{"name": "license", "value": "MIT"}]}

var anns = root.get("annotations");
for (var a : anns) {
  if (!a.isObject()) throw new IllegalStateException("annotation entries must be objects, got: " + a);
}

When it happens

Trigger: An element of the metadata `annotations` array is a string, number, or other non-object value, so parsePObject returns a non-PObject result.

Common situations: Hand-edited metadata with scalar annotation entries; custom publishing scripts serializing annotations as strings; corrupted or partially written metadata artifacts.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• object
• array
• value
• Invalid DataSize unit symbol:
• double

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