apple/pkl · error · FormatException

string

Error message

string

What it means

Thrown by parseAuthors when an element inside the authors JSON array is not a String (or is null). Each author entry must be a plain string; the FormatException names the expected type "string" and the offending element's class (Void.class is used to represent null).

Source

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

    throw new PklException("Could not read annotation. Invalid object type: " + obj.getClass());
  }

  public static Checksums parseChecksums(Object obj) throws JsonParseException {
    if (!(obj instanceof JsObject jsObj)) {
      throw new FormatException("object", obj.getClass());
    }
    var sha256 = jsObj.getString("sha256");
    return new Checksums(sha256);
  }

  public static List<String> parseAuthors(Object obj) throws JsonParseException {
    if (!(obj instanceof JsArray arr)) {
      throw new FormatException("array", obj.getClass());
    }
    var ret = new ArrayList<String>(arr.size());
    for (var elem : arr) {
      if (!(elem instanceof String string)) {
        throw new FormatException("string", elem != null ? elem.getClass() : Void.class);
      }
      ret.add(string);
    }
    return ret;
  }

  private final String name;
  private final PackageUri packageUri;
  private final Version version;
  private final URI packageZipUrl;
  private final Checksums packageZipChecksums;
  private final Map<String, RemoteDependency> dependencies;
  private final @Nullable String sourceCodeUrlScheme;
  private final @Nullable URI sourceCode;
  private final @Nullable URI documentation;
  private final @Nullable String license;
  private final @Nullable String licenseText;
  private final @Nullable List<String> authors;

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Convert each authors entry to a plain string (e.g. "John <john@example.com>")
2. Regenerate the metadata with the official Pkl serializer
3. Pre-validate that every element of the authors array is a string before parsing

Example fix

// before
"authors": ["Jane", {"name": "John"}]
// after
"authors": ["Jane", "John"]

boolean allAuthorsAreStrings(Object o) {
  return o instanceof List<?> l && l.stream().allMatch(e -> e instanceof String);
}

if (!(elem instanceof String s)) { throw new IllegalArgumentException("each author entry must be a string"); }

try {
  var authors = DependencyMetadata.parseAuthors(raw);
} catch (FormatException e) {
  log.error("Found a non-string author entry; flatten structured author objects to strings", e);
}

When it happens

Trigger: Parsing metadata like {"authors":["Jane", {"name":"John"}]} or {"authors":[null]} — any non-string array element.

Common situations: Metadata generated by third-party tooling that emits structured author objects (name/email objects) instead of plain strings, a convention used by other ecosystems but not Pkl.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• double
• FormatException(key, "integer", ret.getClass())
• FormatException(key, "string", ret.getClass())
• FormatException(key, "object", ret.getClass())
• FormatException(key, "array", ret.getClass())

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