t8y2/dbx · error · IllegalArgumentException

offset is only supported when startPosition is offset

Error message

offset is only supported when startPosition is offset

What it means

When startPosition is "offset", KafkaAgent requires an explicit offset value because it cannot infer where to start. If offset is null/missing in that mode, the driver throws this IllegalArgumentException during validatePeekRequest.

Source

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

    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) {
            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
    ) {

View on GitHub (pinned to c0390bff16)

Solutions

Provide a non-negative offset when startPosition is "offset".
Use startPosition "earliest" or "latest" if you don't know the offset.
Fetch a starting offset first (e.g. via offsets lookup or a prior peek result) before using startPosition="offset".

Example fix

// before
{"startPosition": "offset"}

// after
{"startPosition": "offset", "offset": 1284}

Defensive patterns

Strategy: validation

Validate before calling

if ("offset".equals(startPosition) && offset == null) {
    throw new IllegalArgumentException("offset is required when startPosition=offset");
}

Type guard

boolean hasRequiredOffset(String startPosition, Long offset) {
    return !"offset".equals(startPosition) || offset != null;
}

Try / catch

try {
    return agent.peek(conn, req);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("offset is required when startPosition is offset")) {
        req.startPosition = "latest"; // degrade gracefully
        return agent.peek(conn, req);
    } else throw e;
}

Prevention

Only use startPosition="offset" when you actually have an offset value
Capture offsets from prior peek/seek results before using offset mode
Validate the full (startPosition, offset) pair as a unit, not field-by-field

When it happens

Trigger: Sending startPosition="offset" without an offset field (or with JSON null) in the peek request.

Common situations: Switching startPosition to 'offset' in config without adding the offset field; a form where the offset input was left blank; deserializers dropping absent fields so the driver sees null.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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