apple/pkl · error · VmException

invalidConverterPath

invalidConverterPath

Error message

invalidConverterPath

What it means

Pkl's path-based output converters (e.g. `output.converters` with `xml`/`json` path specs) use PathSpecParser.parse to parse a path spec string into path parts. The '^' character may only appear at index 0 of the spec, where it denotes the top-level value; anywhere else the spec is syntactically invalid and this evalError is thrown. The error message is `invalidConverterPath` followed by the offending path spec.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/stdlib/PathSpecParser.java:50

   * VmValueConverter.TOP_LEVEL_VALUE
   */
  Object[] parse(String pathSpec) {
    var result = new ArrayList<>();

    // 0 -> start or after leading `^`
    // 1 -> in property
    // 2 -> in element
    // 3 -> after `]`
    // 4 -> after `.*`
    // 5 -> after `[*`
    var state = 0;

    var partStartIdx = 0;
    var codePoints = pathSpec.codePoints().toArray();
    for (var idx = 0; idx < codePoints.length; idx++) {
      switch (codePoints[idx]) {
        case '^' -> {
          if (idx != 0) throw invalidPattern(pathSpec);
          result.add(VmValueConverter.TOP_LEVEL_VALUE);
          partStartIdx = 1;
        }
        case '.' -> {
          switch (state) {
            case 1 -> {
              int count = idx - partStartIdx;
              if (count == 0) throw invalidPattern(pathSpec);
              result.add(Identifier.get(new String(codePoints, partStartIdx, count)));
            }
            case 3, 4 -> {}
            default -> throw invalidPattern(pathSpec);
          }
          partStartIdx = idx + 1;
          state = 1;
        }
        case '[' -> {
          switch (state) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Remove the '^' from non-leading positions; '^' is only valid as the first character.
2. If you meant to target the top-level value, use a spec that is exactly "^" or start the spec with '^' followed by the rest of the path (e.g. "^.foo").
3. Re-check the path spec syntax: properties are separated by '.', element keys are in '[...]'.

Example fix

// before
converter.pathSpec = "foo^.bar"
// after
converter.pathSpec = "foo.bar"

function isValidPklPathSpec(spec) {
  return typeof spec === "string" && (spec.indexOf("^") === -1 || spec.startsWith("^"));
}

try {
  render(converter)
} catch (e) {
  if (String(e.message).includes("invalidConverterPath")) {
    throw new Error(`Malformed Pkl path spec: ${pathSpec}`);
  }
  throw e;
}

When it happens

Trigger: Calling PathSpecParser.parse (via a Pkl path-based output converter) with a spec containing '^' at any position other than the first character, e.g. `foo^.bar` or `a.^`.

Common situations: Typo in an output converter path spec in a Pkl module, concatenating specs where '^' ends up mid-string, copying a spec snippet that includes the top-level marker into a sub-path.

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

• Cannot parse `%s` as number.
• missingDelimiter
• unexpectedEndOfFile
• stringContentMustBeginOnNewLine
• stringIndentationMustMatchLastLine

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