karatelabs/karate · error · RuntimeException

toBytes() argument must be a list of numbers, got

Error message

toBytes() argument must be a list of numbers, got: {className}

What it means

karate.toBytes() accepts a byte[] or a List; anything else cannot be interpreted as a byte sequence, so the library throws this error with the actual Java class name of the argument. This is the top-level type guard after the arity check and before element-wise conversion.

Solutions

1. Pass a List of numbers instead: karate.toBytes([72, 105]).
2. If you have a string, convert it to char codes first, or use string-to-byte helpers elsewhere in the API.
3. Check what the argument actually is at runtime; the message's class name tells you which type leaked in.

Example fix

// before
var bytes = karate.toBytes('hello')
// after
var bytes = karate.toBytes([104, 101, 108, 108, 111])

if (arg != null && !Array.isArray(arg) && !(arg instanceof (Java.type('byte[]').class) || true)) { /* in JS, check for List-like */ }
if (typeof arg === 'string' || typeof arg === 'number') { throw new Error('toBytes() needs a list of numbers, not ' + typeof arg) }

function isByteList(v) { return v != null && Array.isArray(v) }

try { var bytes = karate.toBytes(arg) } catch (e) { if (('' + e).indexOf('must be a list of numbers') >= 0) { karate.logger.warn('toBytes got: ' + ('' + e)); bytes = null } throw e }

When it happens

Trigger: karate.toBytes('hello') passing a string; karate.toBytes(123) passing a number; passing a Map or other non-List, non-byte[] object.

Common situations: Trying to encode a string as bytes with toBytes (use a different mechanism or convert to char codes); passing JSON directly instead of a numeric array; wrong variable ordering in a script.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• toBytes() list must contain only numbers, got
• toBytes() needs one argument: a list of numbers
• xmlPath() first argument must be XML node or string, but was
• read() needs at least one argument
• sysenv() needs the environment-variable name

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/KarateJsUtils.java:566

            if (list.isEmpty()) {
                return "";
            }
            return DataUtils.toCsv(list);
        };
    }

    @SuppressWarnings("unchecked")
    static JavaInvokable toBytes() {
        return args -> {
            if (args.length < 1) {
                throw new RuntimeException("toBytes() needs one argument: a list of numbers");
            }
            Object arg = args[0];
            if (arg instanceof byte[]) {
                return arg; // already bytes
            }
            if (!(arg instanceof List)) {
                throw new RuntimeException("toBytes() argument must be a list of numbers, got: " + arg.getClass().getName());
            }
            List<Object> list = (List<Object>) arg;
            byte[] bytes = new byte[list.size()];
            for (int i = 0; i < list.size(); i++) {
                Object item = list.get(i);
                if (item instanceof Number num) {
                    bytes[i] = num.byteValue();
                } else {
                    throw new RuntimeException("toBytes() list must contain only numbers, got: " + item.getClass().getName() + " at index " + i);
                }
            }
            return bytes;
        };
    }

    static JavaInvokable toJson() {
        return args -> {
            if (args.length < 1) {

View on GitHub (pinned to a22eb90246)