apple/pkl · error · FormatException
array
Error message
array
What it means
DependencyMetadata.parseAnnotations throws FormatException("array", ann.getClass()) when the `annotations` field of dependency metadata is not a JSON array. The parser expects a list of annotation objects; a non-array value (object, string, null) fails. Like the other FormatExceptions here, it indicates a malformed metadata file.
Source
Thrown at pkl-core/src/main/java/org/pkl/core/packages/DependencyMetadata.java:169
dependencies.get(
key,
(dep) -> {
if (!(dep instanceof JsObject obj)) {
throw new FormatException("object", dep.getClass());
}
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;View on GitHub (pinned to f3efcbfc9b)
Solutions
- Write `annotations` as a JSON array, e.g. [ {...} ], even for a single annotation.
- Regenerate the metadata with `pkl project package`.
- Compare against a known-good published package's metadata shape and fix the producer.
- Remove stray `annotations` fields if they are unnecessary for your package.
Example fix
// before
{"annotations": {"author": "me"}}
// after
{"annotations": [{"name": "author", "value": "me"}]} Defensive patterns
Strategy: validation
Validate before calling
if (root.has("annotations") && !root.get("annotations").isArray())
throw new IllegalStateException("metadata 'annotations' must be a JSON array"); Prevention
- Always wrap annotations in an array, even for a single entry.
- Generate metadata via `pkl project package` rather than hand-editing.
- Validate the full metadata schema in CI.
- Diff hand-edited metadata against a known-good published example.
When it happens
Trigger: Parsing package metadata where `annotations` is missing its array shape — e.g. written as a single object instead of a one-element array, or as a string.
Common situations: Hand-authoring metadata and forgetting the array wrapper around a single annotation; custom metadata generators writing the wrong shape; schema drift between metadata producers and consumers.
Understand the failure class
Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.
Related errors
AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08).
Data as JSON: /api/errors/83ba44459c00a68e.
Report an issue: GitHub.