t8y2/dbx · error · IllegalArgumentException

" + name + " must be a non-negative integer

Error message

" + name + " must be a non-negative integer

What it means

nonNegativeExactLong requires each numeric field (e.g. "partition", "offset") to be present, a JSON number primitive, non-negative, and integral. Missing fields, strings, booleans, negatives, or fractional numbers throw IllegalArgumentException "<name> must be a non-negative integer" (KafkaAgent.java:1549 and 1554).

Source

Thrown at agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java:1549

            if (offsets.put(topicPartition, new OffsetAndMetadata(offset)) != null) {
                throw new IllegalArgumentException("duplicate partition in offsets: " + partition);
            }
        }
        return offsets;
    }

    private static int nonNegativeExactInt(JsonObject object, String name) {
        long value = nonNegativeExactLong(object, name);
        if (value > Integer.MAX_VALUE) {
            throw new IllegalArgumentException(name + " is outside the supported integer range");
        }
        return (int) value;
    }

    private static long nonNegativeExactLong(JsonObject object, String name) {
        JsonElement element = object.get(name);
        if (element == null || !element.isJsonPrimitive() || !element.getAsJsonPrimitive().isNumber()) {
            throw new IllegalArgumentException(name + " must be a non-negative integer");
        }
        try {
            java.math.BigDecimal decimal = element.getAsBigDecimal();
            if (decimal.signum() < 0 || decimal.stripTrailingZeros().scale() > 0) {
                throw new IllegalArgumentException(name + " must be a non-negative integer");
            }
            return decimal.longValueExact();
        } catch (ArithmeticException error) {
            throw new IllegalArgumentException(name + " is outside the supported integer range", error);
        }
    }

    static OffsetSpec offsetSpecForPosition(String position, Long timestampMs) {
        String normalized = position == null ? "latest" : position.trim().toLowerCase(Locale.ROOT);
        return switch (normalized) {
            case "earliest" -> OffsetSpec.earliest();
            case "latest", "" -> OffsetSpec.latest();
            case "timestamp" -> {

View on GitHub (pinned to c0390bff16)

Solutions

1. Send each field as a bare non-negative JSON integer, e.g. {"partition":0,"offset":100}
2. Unquote numeric values (remove surrounding quotes) in the payload
3. Replace sentinel values like -1/null with a proper position option (e.g. startPosition=latest) instead of an offset
4. Round or reject fractional values before sending

Example fix

// before
{"offsets": [{"partition":"0","offset":-1}]}
// after
{"offsets": [{"partition":0,"offset":100}]}

function checkNum(o){ for (const n of ['partition','offset']) { const v=o[n]; if (typeof v !== 'number' || !Number.isInteger(v) || v < 0) throw new Error(n+' must be a non-negative integer'); } }

function isNonNegInt(v){ return typeof v === 'number' && Number.isInteger(v) && v >= 0; }

try { agent.execute(req); } catch (e) { if (String(e.message).includes('must be a non-negative integer')) { /* fix field type/value named in message */ } else throw e; }

When it happens

Trigger: Omitting a required field; passing it as a string ("42" or "abc"); passing a negative value (-1); passing a decimal (1.5); passing null/boolean.

Common situations: Treating offsets as strings after JSON round-trips through a system that quotes numbers; using -1 or null as a sentinel for 'latest'; JavaScript number formatting producing floats.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• offsets must contain at least one partition offset
• each offset must be an object
• duplicate partition in offsets: " + partition
• " + name + " is outside the supported integer range
• timestampMs is required when position is timestamp

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/a607f721d34a9d39. Report an issue: GitHub.