karatelabs/karate · error · JsErrorException

Cannot convert non-integer number to BigInt

Error message

Cannot convert non-integer number to BigInt

What it means

BigInt() called with a JavaScript number that is finite but not a whole number (or throws a sibling RangeError if non-finite) throws this RangeError, matching the ECMAScript BigInt::NumberToBigInt abstract operation. Karate's embedded JS engine enforces the spec rule that only integral numbers can be converted into an arbitrarily large BigInteger.

Solutions

1. Round or truncate the number first: BigInt(Math.trunc(1.5))
2. Verify the value is integral at runtime before converting: if (Number.isInteger(x)) BigInt(x)
3. If a fraction is expected, keep it as a Number or scale it (BigInt(Math.round(19.99 * 100))) instead
4. Parse the value from a string without the fractional part: BigInt('19') instead of BigInt(19.0 from string)

Example fix

// before
let bi = BigInt(avgLatency); // avgLatency = 12.5 -> RangeError
// after
let bi = BigInt(Math.trunc(avgLatency)); // or Number.isInteger(avgLatency) ? BigInt(avgLatency) : 0n

function toBigIntSafe(x) {
  if (typeof x !== 'number') return null;
  if (!Number.isFinite(x)) return null;
  if (!Number.isInteger(x)) return null;
  return BigInt(x);
}

const isBigIntable = (x) => typeof x === 'number' && Number.isFinite(x) && Number.isInteger(x);

let bi;
try { bi = BigInt(x); } catch (e) {
  if (e instanceof RangeError) bi = BigInt(Math.trunc(x));
  else throw e;
}

When it happens

Trigger: BigInt(1.5), BigInt(0.1), BigInt(-2.0001), or BigInt(x) where x comes from arithmetic like 10/3 or a parsed decimal JSON number.

Common situations: Converting numeric API response fields (averages, ratios, prices like 19.99) to BigInt; dividing integers in Karate JS before passing to BigInt; using Math results (Math.sqrt(2)) as BigInt input.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot convert non-finite number to BigInt
• ToIndex: value must be non-negative
• toString() radix must be between 2 and 36
• Cannot convert a BigInt to a number using unary +
• array index too large for dense storage:

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

Appendix: source

Thrown at karate-js/src/main/java/io/karatelabs/js/JsBigIntConstructor.java:97

    // input is guaranteed primitive.
    static BigInteger toBigInt(Object value) {
        return toBigInt(value, null);
    }

    private static BigInteger primitiveToBigInt(Object value) {
        if (value instanceof BigInteger bi) {
            return bi;
        }
        if (value instanceof Boolean b) {
            return b ? BigInteger.ONE : BigInteger.ZERO;
        }
        if (value instanceof Number n) {
            double d = n.doubleValue();
            if (!Double.isFinite(d)) {
                throw JsErrorException.rangeError("Cannot convert non-finite number to BigInt");
            }
            if (d != Math.floor(d)) {
                throw JsErrorException.rangeError("Cannot convert non-integer number to BigInt");
            }
            return new BigDecimal(d).toBigInteger();
        }
        if (value instanceof String s) {
            String trimmed = s.trim();
            if (trimmed.isEmpty()) {
                return BigInteger.ZERO;
            }
            try {
                if (trimmed.length() > 2 && trimmed.charAt(0) == '0') {
                    char c = trimmed.charAt(1);
                    if (c == 'x' || c == 'X') return new BigInteger(trimmed.substring(2), 16);
                    if (c == 'o' || c == 'O') return new BigInteger(trimmed.substring(2), 8);
                    if (c == 'b' || c == 'B') return new BigInteger(trimmed.substring(2), 2);
                }
                return new BigInteger(trimmed);
            } catch (NumberFormatException e) {
                throw JsErrorException.syntaxError("Cannot convert " + s + " to a BigInt");

View on GitHub (pinned to a22eb90246)