apple/pkl · error · FormatException

object

Error message

object

What it means

Thrown by ImportGraph.parseImports when decoding the imports section of a serialized (JavaScript-shape) import graph: each entry must be a JsArray of JsObject elements. This FormatException means an element of the array was not a JS object (or was null), so an Import cannot be parsed from it.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ImportGraph.java:76

    var imports = parseImports(parsed.getObject("imports"));
    var resolvedImports = parseResolvedImports(parsed.getObject("resolvedImports"));
    return new ImportGraph(imports, resolvedImports);
  }

  private static Map<URI, Set<Import>> parseImports(Json.JsObject jsObject)
      throws JsonParseException {
    var ret = new TreeMap<URI, Set<Import>>();
    for (var entry : jsObject.entrySet()) {
      try {
        var key = new URI(entry.getKey());
        var value = entry.getValue();
        var set = new TreeSet<Import>();
        if (!(value instanceof JsArray array)) {
          throw new FormatException("array", value == null ? Void.class : value.getClass());
        }
        for (var elem : array) {
          if (!(elem instanceof JsObject importObj)) {
            throw new FormatException("object", elem == null ? Void.class : elem.getClass());
          }
          set.add(parseImport(importObj));
        }
        ret.put(key, set);
      } catch (URISyntaxException e) {
        throw new MappingException(entry.getKey(), e);
      }
    }
    return ret;
  }

  private static ImportGraph.Import parseImport(Json.JsObject jsObject) throws JsonParseException {
    var uri = jsObject.getURI("uri");
    return new Import(uri);
  }

  private static Map<URI, URI> parseResolvedImports(Json.JsObject jsObject)
      throws JsonParseException {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Inspect the imports array in the import graph JSON and fix or remove the malformed (null/non-object) element
2. Regenerate the import graph / clear the build cache so a fresh, valid graph is produced
3. Check the Pkl version consistency between tools that write and read the graph

Example fix

// before: imports: ["module:/a.pkl"]
// after:  imports: [{"uri": "module:/a.pkl"}]

for (var i = 0; i < importsJson.length(); i++) {
  if (importsJson.get(i) == null || !(importsJson.get(i) instanceof JsObject)) {
    throw new IllegalArgumentException("imports[" + i + "] must be an object");
  }
}

if (!(value instanceof JsArray array)) throw new FormatException("array", value.getClass());
for (var elem : array) {
  if (!(elem instanceof JsObject obj)) throw new FormatException("object", elem.getClass());
}

try {
  graph.imports();
} catch (FormatException e) {
  // e shows expected type vs actual type; inspect and repair the import graph JSON
  LOG.error("Malformed import graph: {}", e.getMessage());
}

When it happens

Trigger: Calling imports() on an ImportGraph whose underlying JSON has an imports array containing a null or non-object element (e.g. a string, number, or boolean instead of an object with uri/relation fields).

Common situations: Hand-edited or tool-generated import-graph JSON, output from an older/newer Pkl version with a changed schema, or a build cache corrupted or truncated mid-write.

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

• string
• JavaType token must be parameterized.
• Failed to convert `pkl.base#String` to `java.net.URI`.
• Failed to convert `pkl.base#String` to `java.net.URL`.
• Failed to convert `pkl.base#String` to `java.nio.file.Path`.

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