apple/pkl · error · FormatException

array

Error message

array

What it means

ImportGraph.parseImports validates the JSON structure of a module-import cache/graph file. When the value mapped to a module URI key is not a JSON array of import objects, it throws FormatException("array", actualClass), i.e. 'expected array but found <type>'. This guards against corrupt or hand-edited import-graph cache files being fed to the evaluator.

Source

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

  /** Parses the provided JSON into an import graph. */
  public static ImportGraph parseFromJson(String input) throws JsonParseException {
    var parsed = Json.parseObject(input);
    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);

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Delete the corrupted cache entry/directory (e.g. ~/.cache/pkl or the project .pkl cache) and re-run to regenerate.
2. Ensure all Pkl processes use the same Pkl version so cache formats match.
3. Don't hand-edit cache files; regenerate them via the tooling.
4. If constructing the graph programmatically, ensure each URI maps to a JSON array of import objects.

Example fix

// before (corrupt cache entry)
{"file:///proj/Main.pkl": {"uri": "..."}}
// after
{"file:///proj/Main.pkl": [{"uri": "file:///proj/Dep.pkl", "isImportedFromModule": false}]}

// validate a parsed import-graph JSON before handing it to the evaluator
for (var entry : graph.entrySet()) {
  if (!(entry.getValue() instanceof List<?> list) || list.stream().anyMatch(o -> !(o instanceof Map))) {
    throw new IllegalStateException("Corrupt import graph entry for " + entry.getKey());
  }
}

static boolean isValidImportGraphEntry(Object value) {
  return value instanceof List<?> list
      && !list.isEmpty()
      && list.stream().allMatch(elem -> elem instanceof Map<?, ?>);
}

try {
  evaluator.evaluate(source);
} catch (PklException e) {
  if (e.getMessage() != null && e.getMessage().contains("array")) {
    Files.deleteIfExists(cacheFile); // drop corrupt cache and retry
    return evaluateFresh(source);
  }
  throw e;
}

When it happens

Trigger: Loading an import graph cache (used by pkl CLI caching / evaluation caching via the imports entry point) where an entry's value is null, a JSON object/string/number instead of an array of {import objects}. Caused by a corrupted, truncated, or manually edited cache file, or an incompatible cache format from a different Pkl version.

Common situations: Stale or corrupted ~/.cache/pkl import-graph entries after an aborted run or version upgrade; sharing cache dirs between Pkl versions; hand-editing cache JSON.

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

• Error deserializing `${path.toUri()}`.
• Values of type `Duration` cannot be rendered as JSON. Value:
• Values of type `DataSize` cannot be rendered as JSON. Value:
• Values of type `Bytes` cannot be rendered as JSON. Value: %s
• Maps containing non-String keys cannot be rendered as JSON.

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