apple/pkl · error · VmException

yamlParseError

yamlParseError

Error message

yamlParseError

What it means

`yaml.parse` throws `yamlParseError` when the YAML engine (snakeyaml-engine) fails to parse the input text for any reason other than the alias-limit. The engine exception message is attached as a hint, e.g. syntax errors, bad indentation, invalid characters, duplicate keys, or disallowed tags.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/stdlib/yaml/ParserNodes.java:81

      var uri = (String) VmUtils.readMember(resource, Identifier.URI, callNode);
      return doParse(self, text, uri);
    }

    private Object doParse(VmTyped self, String text, String uri) {
      var converter = PklConverter.fromParser(self);
      var load = createLoad(self, text, uri, converter);

      try {
        var document = load.loadFromString(text);
        return converter.convert(document, List.of());
      } catch (YamlEngineException e) {
        if (e.getMessage()
            .startsWith("Number of aliases for non-scalar nodes exceeds the specified")) {
          throw exceptionBuilder()
              .evalError("yamlParseErrorTooManyAliases", getMaxCollectionAliases(self))
              .build();
        }
        throw exceptionBuilder().evalError("yamlParseError").withHint(e.getMessage()).build();
      }
    }
  }

  public abstract static class parseAll extends ExternalMethod1Node {
    @Specialization
    @TruffleBoundary
    protected VmList eval(VmTyped self, String text) {
      var uri = "input_string";
      return doParseAll(self, text, uri);
    }

    @Specialization
    @TruffleBoundary
    protected Object eval(
        VmTyped self, VmTyped resource, @Cached("create()") IndirectCallNode callNode) {
      var text = (String) VmUtils.readMember(resource, Identifier.TEXT, callNode);
      var uri = (String) VmUtils.readMember(resource, Identifier.URI, callNode);

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Read the hint message to find the line/column of the first syntax error and fix it
2. Run the text through a YAML linter (yamllint) or an online YAML validator to locate issues
3. Replace tab characters with spaces — YAML forbids tabs for indentation
4. Confirm the file is actually YAML and completely downloaded/uncorrupted

Example fix

// before
key:
	subkey: 1
// after
key:
  subkey: 1

// avoid tabs & non-space indentation before parsing
if (text.contains("\t")) text = text.replaceAll("\t", "  ")

try {
  doc = yaml.parse(text)
} catch (e: PklException) {
  trace("YAML error: ${e.message}")  // hint has line/column
  throw e
}

When it happens

Trigger: Calling `yaml.parse(text)` where `text` is not valid YAML: wrong indentation, tabs for indentation, unbalanced flow collections, invalid mapping structure, bad escape sequences, or content that is JSON/CSV/XML by mistake. Raised in ParserNodes.doParse.

Common situations: Hand-edited YAML config with inconsistent indentation; copying YAML from docs that lost whitespace; parsing JSON-lookalike content with unsupported syntax; files saved with BOM or control characters.

Related errors

• jsonParseError
• yamlParseErrorTooManyAliases
• `%s` is too large to fit into a Version.
• `%s` could not be parsed as a semantic version number.
• The top-level value of a YAML stream must have type `Collect

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