apple/pkl · error · PackageLoadError

unsupportedProjectDepsVersion

unsupportedProjectDepsVersion

Error message

unsupportedProjectDepsVersion

What it means

ProjectDeps.parse() reads the schemaVersion field of the .pkl-project-deps.json-style input and only accepts known supported schema versions. An unrecognized (usually newer) schema version makes parsing fail with PackageLoadError('unsupportedProjectDepsVersion').

Solutions

1. Upgrade the Pkl runtime/tooling so supportedSchemaVersions includes the file's schemaVersion
2. Regenerate the deps file with the currently installed CLI version (delete and re-run the resolve command)
3. Check the schemaVersion value in the file and correct it if it was edited by mistake

var obj = Json.parseObject(input);
int v = obj.getInt("schemaVersion");
if (!Set.of(1).contains(v)) throw new IllegalArgumentException("unsupported schemaVersion: " + v);

boolean isSupportedSchema(int v) { return v >= 1 && v <= MAX_SUPPORTED_SCHEMA_VERSION; }

try { ProjectDeps.parse(input); } catch (PackageLoadError e) { /* upgrade Pkl tooling or regenerate deps file */ }

When it happens

Trigger: Calling ProjectDeps.parse(input) where parsed.getInt("schemaVersion") returns a value not in supportedSchemaVersions — e.g. a deps file written by a newer Pkl CLI being parsed by an older runtime.

Common situations: Upgrading the Pkl CLI (writing a new deps schema) while the embedded pkl-core runtime is older; hand-editing schemaVersion; copying deps files between projects produced by different tool versions.

Related errors

• array
• cannotResolveInLocalDependencyNotGlobbable
• cannotResolveInLocalDependencyNotGlobbableNorLocal
• Docsite is not up to date. Expected
• e.getMessage()

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

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/project/ProjectDeps.java:94

 * </pre>
 * </code>
 */
public final class ProjectDeps {
  private static final Set<Integer> supportedSchemaVersions = Set.of(1);

  private final EconomicMap<CanonicalPackageUri, Dependency> resolvedDependencies;

  public static ProjectDeps parse(Path path)
      throws IOException, URISyntaxException, JsonParseException {
    var input = Files.readString(path);
    return parse(input);
  }

  public static ProjectDeps parse(String input) throws JsonParseException {
    var parsed = Json.parseObject(input);
    var schemaVersion = parsed.getInt("schemaVersion");
    if (!supportedSchemaVersions.contains(schemaVersion)) {
      throw new PackageLoadError("unsupportedProjectDepsVersion", schemaVersion);
    }
    var resolvedDependencies =
        parsed.get("resolvedDependencies", ProjectDeps::parseResolvedDependencies);
    return new ProjectDeps(resolvedDependencies);
  }

  private static EconomicMap<CanonicalPackageUri, Dependency> parseResolvedDependencies(
      Object object) throws JsonParseException, URISyntaxException {
    if (!(object instanceof JsObject jsObj)) {
      throw new FormatException("resolvedDependencies", "object", object.getClass());
    }
    var ret = EconomicMaps.<CanonicalPackageUri, Dependency>create(jsObj.size());
    for (var entry : jsObj.entrySet()) {
      Dependency resolvedDependency = parseResolvedDependency(entry);
      var canonicalPackageUri = CanonicalPackageUri.of(entry.getKey());
      ret.put(canonicalPackageUri, resolvedDependency);
    }
    return ret;

View on GitHub (pinned to f3efcbfc9b)