t8y2/dbx · error · IllegalArgumentException

offset must be non-negative when startPosition is offset

Error message

offset must be non-negative when startPosition is offset

What it means

This is the non-legacy branch of validatePeekRequest for negative offsets. When an explicit startPosition is present and equals "offset", a supplied offset below zero is rejected with this IllegalArgumentException. It mirrors error 98 but runs on the explicit-startPosition code path.

Source

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

        }
        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) {
            throw new IllegalArgumentException("offset must be non-negative when startPosition is offset");
        }
    }

    static Long requestedPeekOffset(
        PeekStartPosition startPosition,
        Long offset,
        boolean legacyOffsetRequest,
        long beginningOffset,
        long endOffset
    ) {
        return switch (startPosition) {
            case LATEST -> endOffset > beginningOffset ? beginningOffset : null;
            case OFFSET -> offset;
            case EARLIEST -> legacyOffsetRequest ? offset : beginningOffset;
        };
    }

    static int peekScanLimit(int count, int readablePartitionCount) {

View on GitHub (pinned to c0390bff16)

Solutions

Use offset >= 0 with startPosition="offset".
Omit startPosition and use "earliest"/"latest" semantics instead of negative sentinels.
Add client-side validation mirroring validatePeekRequest before sending.

Example fix

// before
peek(topic, /* partition */ 0, /* startPosition */ "offset", /* offset */ -5);

// after
peek(topic, 0, "offset", 0L); // or use startPosition "latest"

Defensive patterns

Strategy: validation

Validate before calling

if (offset != null && offset < 0) {
    throw new IllegalArgumentException("offset must be non-negative");
}

Type guard

boolean isNonNegativeOffset(Long offset) { return offset == null || offset >= 0; }

Try / catch

try {
    return agent.peek(conn, req);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("offset must be non-negative")) {
        req.offset = Math.max(req.offset, 0L); // or fall back to earliest
        return agent.peek(conn, req);
    } else throw e;
}

Prevention

Run validatePeekRequest-equivalent checks client-side before every peek call
Ensure migrated legacy requests convert negative sentinel offsets to named start positions
Test your request builder against the driver's full validation chain (partition, offset, startPosition)

When it happens

Trigger: Peek request with explicit startPosition="offset" and a negative offset value (e.g. -1 used as a sentinel).

Common situations: Porting code from the legacy bare-offset API where -1 sometimes meant 'auto'; front-end defaults of -1 for 'unset'; mixing legacy and new request shapes so both validation branches fire differently.

Related errors

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