karatelabs/karate · error · JsErrorException

Do not know how to serialize a BigInt

Error message

Do not know how to serialize a BigInt

What it means

JSON.stringify encountered a BigInt value (BigInteger or JsBigInt after unwrapping JS wrappers). JSON has no BigInt representation, so per §25.5.2 the serializer throws a TypeError('Do not know how to serialize a BigInt') instead of emitting invalid JSON.

Solutions

1. Convert BigInt values to strings (or numbers) before serializing, e.g. with a replacer: `(k, v) => typeof v === 'bigint' ? v.toString() : v`.
2. Adjust the Java side to return a String (or a smaller numeric type) for fields destined for JSON.
3. Store big values as strings in the data model instead of BigInteger.
4. Exclude BigInt fields via the replacer or a property filter.

Example fix

// before
var json = karate.stringify(response); // response.id is BigInteger
// after
var json = karate.stringify(response, function(k, v) {
  return (typeof v === 'bigint') ? v.toString() : v;
});

function hasBigInt(v) { if (typeof v === 'bigint') return true; if (v instanceof Map || Array.isArray(v)) return Array.from(v.values ? v.values() : v).some(hasBigInt); if (v && typeof v === 'object') return Object.values(v).some(hasBigInt); return false; }

function isBigIntLike(v) { return typeof v === 'bigint' || v instanceof java.math.BigInteger; }

try { json = karate.stringify(obj); } catch (e) { if (String(e).indexOf('BigInt') !== -1) { json = karate.stringify(obj, function(k, v) { return typeof v === 'bigint' ? v.toString() : v; }); } else { throw e; } }

When it happens

Trigger: Calling karate.stringify(obj) / JSON.stringify(obj) where any reachable property is a BigInt — e.g. values produced by Java interop (Java longs mapped to BigInteger) or explicit JS BigInt literals (123n).

Common situations: Serializing Java method results (long/BigInteger) for match comparisons; logging payloads that include big IDs from Java; storing BigInt-bearing data into JSON files.

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

• Converting circular structure to JSON
• fromJson() needs one argument: a JSON string
• toJson() needs at least one argument
• JS error
• Cannot convert a BigInt to a number using unary +

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

Appendix: source

Thrown at karate-js/src/main/java/io/karatelabs/js/JsJson.java:175

            // A JS throw from user code propagates as-is (spec: SerializeJSONProperty
            // forwards abrupt completions) — the live context keeps the thrown value's
            // JS identity instead of the host-invocation EngineException wrap.
            value = callWithThis(context, replacerFn, holder, new Object[]{key, value});
        }
        if (value instanceof JsFunction) {
            return value; // JSON has no functions; the formatter drops / nulls them
        }
        // §25.5.2: a Symbol value is unrepresentable — omitted as a property,
        // null as an array element. Ahead of the JsValue unwrap because a
        // JsSymbol is a JsObject and would otherwise recurse into "{}".
        if (value instanceof JsSymbol) {
            return Terms.UNDEFINED;
        }
        if (value instanceof JsValue jv && !(value instanceof JsUndefined)) {
            value = jv.getJavaValue(); // Number / String / Boolean / Date wrappers
        }
        if (value instanceof BigInteger || value instanceof JsBigInt) {
            throw JsErrorException.typeError("Do not know how to serialize a BigInt");
        }
        // §25.5.2.2 SerializeJSONNumber: a finite Number is its ToString, a
        // non-finite one is the literal null — JSON has no NaN / Infinity.
        // Only here: Terms.numberToString stays the ToString seam String(NaN) shares.
        if (value instanceof Number n && !Double.isFinite(n.doubleValue())) {
            return null;
        }
        if (!(value instanceof Map<?, ?>) && !(value instanceof List<?>)) {
            return value;
        }
        if (!seen.add(value)) {
            throw JsErrorException.typeError("Converting circular structure to JSON");
        }
        try {
            return value instanceof List<?> list
                    ? serializeArray(context, list, replacerFn, propertyList, seen)
                    : serializeObject(context, value, replacerFn, propertyList, seen);
        } finally {

View on GitHub (pinned to a22eb90246)