karatelabs/karate · error · JsErrorException

Cannot convert to a BigInt

Error message

Cannot convert  to a BigInt

What it means

BigInt() called with a string that is not a valid integer literal (empty, whitespace-only, decimal point, garbage characters) throws this SyntaxError per ECMAScript StringToBigInt. Karate's JS engine surfaces the original string in the message.

Solutions

  1. Trim and test the string against /^-?\d+$/ before calling BigInt(s)
  2. Handle empty strings explicitly (default to 0n or throw your own clear error)
  3. Strip non-numeric suffixes (units, currency symbols) first: BigInt(s.replace(/[^-\d]/g, ''))
  4. For decimal strings, decide on scaling: BigInt(Math.trunc(Number('3.14'))) or work in minor units BigInt('314')

Example fix

// before
let id = BigInt(row.id); // row.id = '' -> SyntaxError
// after
let id = /^-?\d+$/.test(row.id) ? BigInt(row.id) : 0n;
Defensive patterns

Strategy: validation

Validate before calling

function stringToBigInt(s) {
  if (typeof s !== 'string') return null;
  const t = s.trim();
  return /^-?\d+$/.test(t) ? BigInt(t) : null;
}

Type guard

const isBigIntString = (s) => typeof s === 'string' && /^-?\d+$/.test(s.trim());

Try / catch

let bi;
try { bi = BigInt(s); } catch (e) {
  if (e instanceof SyntaxError) bi = 0n; // or surface a domain error
  else throw e;
}

Prevention

When it happens

Trigger: BigInt('') or BigInt(' '), BigInt('3.14'), BigInt('abc'), BigInt('12px') — any string whose new BigInteger(trimmed) parse throws NumberFormatException; empty strings produce the empty-value message 'Cannot convert to a BigInt'.

Common situations: Parsing numeric strings from APIs, CSV cells, or form inputs that are blank or contain units/decimals; JSON keys assumed numeric but holding '12.5' or empty values.

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

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

Appendix: source

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

                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");
            }
        }
        if (value == null || value == Terms.UNDEFINED) {
            throw JsErrorException.typeError("Cannot convert " + (value == null ? "null" : "undefined") + " to a BigInt");
        }
        throw JsErrorException.typeError("Cannot convert object to a BigInt");
    }

    private Object asIntN(Context context, Object[] args) {
        int bits = toIndex(args.length > 0 ? args[0] : Terms.UNDEFINED, (CoreContext) context);
        BigInteger bi = toBigInt(args.length > 1 ? args[1] : Terms.UNDEFINED, (CoreContext) context);
        if (bits == 0) return BigInteger.ZERO;
        // mod 2^bits, then signed reinterpret
        BigInteger mod = BigInteger.ONE.shiftLeft(bits);
        BigInteger r = bi.mod(mod);
        BigInteger half = BigInteger.ONE.shiftLeft(bits - 1);
        if (r.compareTo(half) >= 0) {
            r = r.subtract(mod);

View on GitHub (pinned to a22eb90246)