t8y2/dbx · error · IllegalArgumentException

offset is required when startPosition is offset

Error message

offset is required when startPosition is offset

What it means

Completing the same validation chain as errors 96-97: when startPosition is "offset" and an offset is supplied, it must be >= 0. Negative offsets have no meaning in Kafka, so the driver throws this IllegalArgumentException with the mode-specific message.

Source

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

    ) {
        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
    ) {
        return switch (startPosition) {
            case LATEST -> endOffset > beginningOffset ? beginningOffset : null;
            case OFFSET -> offset;
            case EARLIEST -> legacyOffsetRequest ? offset : beginningOffset;
        };

View on GitHub (pinned to c0390bff16)

Solutions

Pass a non-negative absolute offset with startPosition="offset".
Use startPosition="latest" or "earliest" instead of negative sentinel offsets.
Validate offset >= 0 in client code before constructing the request.

Example fix

// before
{"startPosition": "offset", "offset": -1} // meant 'latest'

// after
{"startPosition": "latest"}

Defensive patterns

Strategy: validation

Validate before calling

if ("offset".equals(startPosition) && offset != null && offset < 0) {
    throw new IllegalArgumentException("offset must be >= 0 when startPosition=offset");
}

Type guard

boolean isValidOffsetForOffsetMode(String startPosition, Long offset) {
    return !"offset".equals(startPosition) || (offset != null && offset >= 0);
}

Try / catch

try {
    return agent.peek(conn, req);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("offset must be non-negative when startPosition is offset")) {
        req.startPosition = "latest";
        req.offset = null;
        return agent.peek(conn, req);
    } else throw e;
}

Prevention

Never use negative sentinels (-1/-2) for 'latest'/'earliest'; use the named start positions
Clamp or reject negative offsets in your client before sending
Add a shared (startPosition, offset) validator reused by all request builders

When it happens

Trigger: Sending startPosition="offset" with offset = -1 or any negative number.

Common situations: Using -1 to mean 'latest' or 'end' (a convention from other systems, e.g. some consumer APIs use -1/-2 sentinels); signed/unsigned arithmetic wrapping; user typing a negative offset in a tool.

Related errors

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