apple/pkl · error

invalidCodePoint

invalidCodePoint

Error message

invalidCodePoint

What it means

IntNodes' codePoint-to-string conversion (Int.prototype.codePointToString or similar) turns an integer into a single-character String only when it is an exact integer and a valid Unicode code point (0..0x10FFFF, excluding the surrogate range per Character.isValidCodePoint semantics). Otherwise it throws the `invalidCodePoint` eval error.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/stdlib/base/IntNodes.java:395

      return self >= start && self <= inclusiveEnd;
    }

    @Specialization
    protected boolean evalFloatFloat(long self, double start, double inclusiveEnd) {
      return self >= start && self <= inclusiveEnd;
    }
  }

  public abstract static class toChar extends ExternalMethod0Node {
    @Specialization
    protected String eval(long self) {
      var codePoint = (int) self;
      if (codePoint == self && Character.isValidCodePoint(codePoint)) {
        return Character.toString(codePoint);
      }

      CompilerDirectives.transferToInterpreter();
      throw exceptionBuilder().evalError("invalidCodePoint", self).build();
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Ensure the integer is in 0..0x10FFFF before conversion.
2. Reject/repair negative or fractional values at the data source.
3. Replace surrogate code units with the combined code point (e.g. 0x1F600 instead of the 0xD83D/0xDE00 pair).
4. Use String.fromCharCode-style composition at the source for multi-unit characters instead of this API.

Example fix

// before
ch = 0x110000.codePointToString()  // invalidCodePoint
// after
ch = if (cp >= 0 && cp <= 0x10FFFF) cp.codePointToString() else "\uFFFD"

function isValidCodePoint(n) {
  return Number.isInteger(n) && n >= 0 && n <= 0x10FFFF && !(n >= 0xD800 && n <= 0xDFFF);
}

function isConvertibleCodePoint(n) {
  return typeof n === "number" && Number.isInteger(n) && n >= 0 && n <= 0x10FFFF;
}

When it happens

Trigger: Calling the code point conversion with an Int that is negative, exceeds 0x10FFFF, is non-integral (e.g. 65.5 via a Float-typed Int node), or lands in the surrogate range — thrown at IntNodes.java:395 when `codePoint == self && Character.isValidCodePoint(codePoint)` fails.

Common situations: Decoding character codes from external data where offsets are off-by-one or byte-swapped, computing code points from arithmetic that produced 0 or negative values, or accidentally passing a full UTF-16 code unit pair instead of a code point.

Related errors

• invalidUnicodeEscapeSequence
• intTooLarge
• unexpectedCharacter
• unterminatedUnicodeEscapeSequence
• Node `%s` of type `%s` does not have a property named `%s`.

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