karatelabs/karate · error · ParserException

unicode escape sequence out of range in template literal

Error message

unicode escape sequence out of range in template literal

What it means

The \u{...} codepoint escape must not exceed 0x10FFFF, the maximum Unicode codepoint. karate-js accumulates hex digits and throws as soon as the value overflows, per the ES spec early error for untagged templates.

Solutions

Clamp or correct the codepoint to <= 0x10FFFF before embedding
Convert from decimal first: use `\u{${cp.toString(16)}}` so the number is hex-encoded
Use String.fromCodePoint(cp) at runtime instead of an escape when the value is dynamic
If pairing surrogates, use the standard formula and validate 0 <= cp <= 0x10FFFF

Example fix

// before
var ch = `\u{${cp}}`;       // cp = 1114112 (0x110000) -> out of range
// after
var ch = String.fromCodePoint(cp); // throws a clearer RangeError if invalid
// or: var esc = `\u{${cp.toString(16)}}`;

Defensive patterns

Strategy: validation

Validate before calling

function codepointInRange(hex) {
  var cp = parseInt(hex, 16);
  return Number.isFinite(cp) && cp >= 0 && cp <= 0x10FFFF;
}
if (!codepointInRange(cpHex)) throw new Error('codepoint exceeds 0x10FFFF: ' + cpHex);

Type guard

null

Try / catch

try {
  karate.eval('var s = `\u{' + cpHex + '}`;');
} catch (e) {
  if (String(e.message).indexOf('out of range') >= 0) {
    var ch = String.fromCodePoint(0x10FFFF); // or clamp/substitute your fallback
  } else throw e;
}

Prevention

Clamp computed codepoints to 0..0x10FFFF before embedding
Encode numbers to hex (toString(16)) — never interpolate decimal values into \u{}
Use String.fromCodePoint at runtime for dynamic codepoints
Verify surrogate-pair math: base 0x10000 plus offset <= 0xFFFFF

When it happens

Trigger: Template literal contains \u{...} with a hex value greater than 10FFFF, e.g. `\u{110000}`, `\u{FFFFFF}`, or an interpolated value like `\u{${bigNumber}}` that isn't a valid codepoint; thrown at JsLexer.java:419.

Common situations: Off-by-one when computing surrogate pairs (e.g. 0x10000 + 0x10FFFF), decimal values interpolated as hex, generated emoji/codepoint tables with bad bounds, porting code that used plain decimal escapes.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/3300e2ee8d93f439. Report an issue: GitHub.

Appendix: source

Thrown at karate-js/src/main/java/io/karatelabs/parser/JsLexer.java:419

                }
                // Unicode escape backslash-u HHHH or backslash-u {H...} — require proper form.
                if (esc == 'u') {
                    char next = peek(1);
                    if (next == '{') {
                        // backslash-u { codepoint } — one or more hex digits, closed by }
                        int j = 2;
                        if (!isHexDigit(peek(j))) {
                            throw new ParserException("invalid unicode escape sequence in template literal");
                        }
                        int codepoint = 0;
                        while (isHexDigit(peek(j))) {
                            char h = peek(j);
                            int v = (h >= '0' && h <= '9') ? h - '0'
                                    : (h >= 'a' && h <= 'f') ? h - 'a' + 10
                                    : h - 'A' + 10;
                            codepoint = (codepoint << 4) | v;
                            if (codepoint > 0x10FFFF) {
                                throw new ParserException("unicode escape sequence out of range in template literal");
                            }
                            j++;
                        }
                        if (peek(j) != '}') {
                            throw new ParserException("invalid unicode escape sequence in template literal");
                        }
                    } else {
                        // backslash-u HHHH — four hex digits
                        if (!isHexDigit(peek(1)) || !isHexDigit(peek(2))
                                || !isHexDigit(peek(3)) || !isHexDigit(peek(4))) {
                            throw new ParserException("invalid unicode escape sequence in template literal");
                        }
                    }
                }
                advance();
                continue;
            }
            advance();

View on GitHub (pinned to a22eb90246)