apple/pkl · error · ParserError

invalidCharacterEscapeSequence

invalidCharacterEscapeSequence

Error message

Invalid character escape sequence `{0}`.

Valid character escape sequences are:  {1}n  {1}r  {1}t  {1}"  {1}\\ {1}<newline>

What it means

A backslash was followed by a character that does not begin a valid escape, and that character was a space or tab not followed by a newline (ruling out a line continuation). Pkl only allows \n, \r, \t, \", \\, and \newline as character escapes, so `\ ` or `\<tab>` with other following content is an invalid character escape sequence. The message echoes the offending two-character sequence and lists valid escapes.

Source

Thrown at pkl-parser/src/main/java/org/pkl/parser/Lexer.java:480

      case 'u' -> lexUnicodeEscape();
      case '\n' -> Token.STRING_ESCAPE_CONTINUATION;
      case '\r' -> {
        if (lookahead == '\n') {
          nextChar();
        }
        yield Token.STRING_ESCAPE_CONTINUATION;
      }
      case ' ', '\t' -> {
        var c = cursor;
        var next = nextChar();
        while (next == ' ' || next == '\t') next = nextChar();
        if (next == '\n' || next == '\r')
          throw lexError(
              ErrorMessages.create("invalidLineContinuationEscapeSequenceWhitespace"),
              c - 2,
              cursor - c + 2);

        throw lexError(
            ErrorMessages.create("invalidCharacterEscapeSequence", "\\" + (char) ch, "\\"),
            c - 2,
            2);
      }
      default ->
          throw lexError(
              ErrorMessages.create("invalidCharacterEscapeSequence", "\\" + (char) ch, "\\"),
              cursor - 2,
              2);
    };
  }

  private Token lexUnicodeEscape() {
    if (lookahead != '{') {
      throw unexpectedChar(lookahead, "{");
    }
    do {
      nextChar();

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Remove the backslash — space does not need escaping in Pkl strings: `"a b"` not `"a\ b"`.
2. If a literal backslash is wanted, double it: `"a\\ b"`.
3. Use one of the valid escapes (\n, \r, \t, \", \\, \newline) as listed in the message.
4. For a line continuation, ensure nothing but the newline follows the `\`.

Example fix

// before
path = "C:\ Program Files"
// after
path = "C:\\ Program Files"

function invalidSpaceEscape(src) { return /\\[ \t]+(?![\r\n])/.test(src); }
if (invalidSpaceEscape(src)) throw new Error('Backslash followed by space/tab is not a valid escape; use \\\\ or remove the backslash');

null

try { tokens = lexer.next(); } catch (e) { if (e.code === 'invalidCharacterEscapeSequence') { console.error('Only \\n \\r \\t \\" \\\\ \\newline are valid'); } throw e; }

When it happens

Trigger: nextString → lexEscape, case ' '/'\t': a `\` is followed by space(s)/tab(s) and the next non-whitespace character is NOT `\n`/`\r` — e.g. `"a\ b"` or `"a\ x"`. The error is reported at the `\` plus following char (2 chars).

Common situations: Trying to escape a space in a regex or path inside a Pkl string (unnecessary — spaces need no escaping); copy-paste from shell snippets where `\ ` escaped spaces for the shell; typos like `\/` or `\'` in a URL string pasted from another language.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• invalidLineContinuationEscapeSequenceWhitespace
• unexpectedCharacter
• unterminatedUnicodeEscapeSequence
• invalidUnicodeEscapeSequence
• invalidLineContinuationEscapeSequence

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