apple/pkl · error · FormatException

string

Error message

string

What it means

Thrown by ImportGraph.parseResolvedImports when a value in the resolved-imports map is not a JSON string. Each key/value pair must be URI strings mapping an import URI to its resolved URI; this FormatException signals a non-string (or null) value.

Source

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

      }
    }
    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 {
    var ret = new TreeMap<URI, URI>();
    for (var entry : jsObject.entrySet()) {
      try {
        var key = new URI(entry.getKey());
        var value = entry.getValue();
        if (!(value instanceof String str)) {
          throw new FormatException("string", value == null ? Void.class : value.getClass());
        }
        var valueUri = new URI(str);
        ret.put(key, valueUri);
      } catch (URISyntaxException e) {
        throw new MappingException(entry.getKey(), e);
      }
    }
    return ret;
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Fix the offending value in the resolved imports JSON to be a URI string
2. Delete/regenerate the resolved-imports cache file
3. Verify all tools reading/writing the map use the string-to-string URI map schema

Example fix

// before: {"file:///a.pkl": 42}
// after:  {"file:///a.pkl": "file:///resolved/a.pkl"}

for (var e : resolvedJson.entrySet()) {
  if (e.getValue() == null || !(e.getValue() instanceof String)) {
    throw new IllegalArgumentException("resolved import value for " + e.getKey() + " must be a URI string");
  }
}

if (!(value instanceof String str)) throw new FormatException("string", value.getClass());

try {
  graph.resolvedImports();
} catch (FormatException e) {
  LOG.error("Invalid resolved imports map: {}", e.getMessage());
  // fall back to regenerating the graph
}

When it happens

Trigger: Calling resolvedImports() on a graph whose resolvedImports JSON map contains a value that is a number, object, boolean, or null instead of a URI string.

Common situations: Corrupted or hand-edited resolution cache files, schema drift between Pkl versions, or a third-party tool writing resolved import maps in the wrong shape.

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

• object
• 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/451952ceefdf40ac. Report an issue: GitHub.