t8y2/dbx · error · IllegalArgumentException

offsets must contain at least one partition offset

Error message

offsets must contain at least one partition offset

What it means

KafkaAgent's commit-offsets request parsing rejects an "offsets" parameter that is an empty JSON array. Offsets must identify at least one (partition, offset) pair for the target topic, since committing nothing is a no-op the agent refuses to perform. Thrown as IllegalArgumentException from the offsets-parsing helper around KafkaAgent.java:1521.

Source

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

        }

        admin.alterConsumerGroupOffsets(groupId, offsets)
            .all().get(timeout, TimeUnit.MILLISECONDS);
        return Collections.singletonMap("ok", true);
    }

    static Map<TopicPartition, OffsetAndMetadata> explicitConsumerGroupOffsets(JsonObject params, String topic) {
        Map<TopicPartition, OffsetAndMetadata> offsets = new HashMap<>();
        if (!params.has("offsets")) {
            return offsets;
        }
        JsonElement offsetsElement = params.get("offsets");
        if (!offsetsElement.isJsonArray()) {
            throw new IllegalArgumentException("offsets must be an array");
        }
        JsonArray offsetArray = offsetsElement.getAsJsonArray();
        if (offsetArray.isEmpty()) {
            throw new IllegalArgumentException("offsets must contain at least one partition offset");
        }
        for (JsonElement element : offsetArray) {
            if (!element.isJsonObject()) {
                throw new IllegalArgumentException("each offset must be an object");
            }
            JsonObject value = element.getAsJsonObject();
            int partition = nonNegativeExactInt(value, "partition");
            long offset = nonNegativeExactLong(value, "offset");
            TopicPartition topicPartition = new TopicPartition(topic, partition);
            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);

View on GitHub (pinned to c0390bff16)

Solutions

1. Populate offsets with at least one object containing non-negative integer "partition" and "offset" fields before calling
2. Skip the commit call entirely when the offsets list is empty instead of sending an empty array
3. Check that the JSON payload actually contains the offsets you built (e.g. log the request body)

Example fix

// before
agent.execute(Map.of("op","commitOffsets","topic","t","offsets",List.of()));
// after
List<Map<String,Object>> offsets = List.of(Map.of("partition",0,"offset",42L));
agent.execute(Map.of("op","commitOffsets","topic","t","offsets",offsets));

if (!Array.isArray(offsets) || offsets.length === 0) throw new Error('offsets must contain at least one entry');

function hasOffsets(o) { return Array.isArray(o) && o.length > 0; }

try { agent.execute(req); } catch (e) { if (e instanceof IllegalArgumentException && e.getMessage().contains('offsets must contain')) { /* fix payload */ } else throw e; }

When it happens

Trigger: Calling the Kafka agent's offset-commit operation with params.offsets = [] (or an offsets field that serializes to an empty array).

Common situations: Building the offsets array programmatically from a filter/map that produced no results; a caller that always includes the offsets key even when there is nothing to commit.

Related errors

• each offset must be an object
• duplicate partition in offsets: " + partition
• " + name + " is outside the supported integer range
• " + name + " must be a non-negative integer
• timestampMs is required when position is timestamp

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