t8y2/dbx · error · IllegalArgumentException

partition must be non-negative

Error message

partition must be non-negative

What it means

validatePeekRequest checks that, when supplied, the peek partition index is >= 0. Kafka partitions are zero-based, so a negative value can never be valid. The driver throws this IllegalArgumentException before touching the cluster.

Source

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

        if (value == null) {
            return PeekStartPosition.EARLIEST;
        }
        return switch (value.trim().toLowerCase(Locale.ROOT)) {
            case "earliest" -> PeekStartPosition.EARLIEST;
            case "latest" -> PeekStartPosition.LATEST;
            case "offset" -> PeekStartPosition.OFFSET;
            default -> throw new IllegalArgumentException("Unsupported peek startPosition: " + value);
        };
    }

    static void validatePeekRequest(
        PeekStartPosition startPosition,
        boolean explicitStartPosition,
        Integer partition,
        Long offset
    ) {
        if (partition != null && partition < 0) {
            throw new IllegalArgumentException("partition must be non-negative");
        }
        if (!explicitStartPosition) {
            // Older clients used offset directly without a startPosition field.
            if (offset != null && offset < 0) {
                throw new IllegalArgumentException("offset must be non-negative");
            }
            return;
        }
        if (startPosition != PeekStartPosition.OFFSET) {
            if (offset != null) {
                throw new IllegalArgumentException("offset is only supported when startPosition is offset");
            }
            return;
        }
        if (offset == null) {
            throw new IllegalArgumentException("offset is required when startPosition is offset");
        }
        if (offset < 0) {

View on GitHub (pinned to c0390bff16)

Solutions

1. Pass null (omit the field) instead of -1 when no partition should be pinned.
2. Ensure the client serializes partition as null rather than a sentinel negative number.
3. Clamp/validate partition >= 0 before sending the request.

Example fix

// before
Integer partition = unset ? -1 : userPartition;
agent.peek(conn, topic, partition);

// after
Integer partition = unset ? null : userPartition;
agent.peek(conn, topic, partition);

if (partition != null && partition < 0) {
    throw new IllegalArgumentException("partition must be >= 0 or null");
}

boolean isValidPartition(Integer partition) { return partition == null || partition >= 0; }

try {
    return agent.peek(conn, topic, partition);
} catch (IllegalArgumentException e) {
    if (e.getMessage().equals("partition must be non-negative")) {
        return agent.peek(conn, topic, null); // treat sentinel as unset
    } else throw e;
}

When it happens

Trigger: Passing partition = -1 (often as a sentinel for 'any partition' or 'unset') to the peek API along with other parameters.

Common situations: Using -1 as a 'not specified' default in client code; converting an unsigned UI value with an error sentinel; SQL-influenced code where -1 sometimes means 'all'.

Related errors

• Kafka partition ${partition} does not exist for topic '${top
• offsets must be an array
• Peek message count must be between 1 and " + MAX_PEEK_MESSAG
• ${name} must be a positive integer
• Unsupported peek startPosition: ${value}

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