apple/pkl · error · ParserError

wrongHeaders

wrongHeaders

Error message

ErrorMessages.create("wrongHeaders", messageArg)

What it means

The Pkl parser throws ParserError with the "wrongHeaders" message when it encounters a declaration whose member modifiers/annotations (header) are not allowed to be present for that kind of member. ensureEmptyHeaders is called at grammar positions where a member must carry no modifiers (e.g. certain object members or entries), and any non-empty header there is a syntax error.

Solutions

1. Open the file at the span reported in the error and remove the modifiers/annotations from the offending member.
2. Check the Pkl language spec for which member kinds accept which modifiers (e.g. `hidden` only on properties, not entries).
3. If the error appeared after a Pkl version upgrade, check release notes for stricter grammar rules.
4. Run the file through `pkl format` or an editor with Pkl LSP to spot misplaced modifiers.

Example fix

// before
"key" hidden = 1 // entry cannot have `hidden` header
// after
"key" = 1

// Validate with the parser before use
try {
  new Parser().parseModule(pklSource);
} catch (ParserError e) {
  // surface e.getMessage() + span to the author
}

try {
  parse(pklSource);
} catch (ParserError e) {
  logger.error("Pkl syntax error at " + e.getSpan() + ": " + e.getMessage());
}

When it happens

Trigger: Parsing a .pkl module that places modifiers or annotations on a grammar position that requires an empty member header — e.g. adding `hidden`, `fixed`, `abstract`, or an annotation to a member kind that forbids them (object entries, amends bodies, etc.).

Common situations: Hand-editing a Pkl config file and adding a modifier in the wrong place; copy-pasting modifiers between member kinds; typos that make the parser read a token as a modifier instead of part of the value.

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

• '" + ch + "'
• closingStringDelimiterMustBeginOnNewLine
• closingStringDelimiterMustBeginOnNewLine
• ':'
• ErrorMessages.create(errorKey, args)

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

Appendix: source

Thrown at pkl-parser/src/main/java/org/pkl/parser/ParserImpl.java:1871

    }
    return new FullToken(tk, lexer.span(), lexer.getNewLinesBetween());
  }

  /**
   * Backtrack to the previous token.
   *
   * <p>Can only backtrack one token.
   */
  private void backtrack() {
    assert !backtracking;
    lookahead = prev.token;
    spanLookahead = prev.span;
    backtracking = true;
  }

  private void ensureEmptyHeaders(MemberHeader header, String messageArg) {
    if (header.isNotEmpty()) {
      throw new ParserError(
          ErrorMessages.create("wrongHeaders", messageArg), header.span(spanLookahead));
    }
  }

  private record FullToken(Token token, Span span, int newLinesBetween) {
    String text(Lexer lexer) {
      return lexer.textFor(span.charIndex(), span.length());
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)