apache/kafka · error · java.lang.IllegalArgumentException

Invalid negative offset

Error message

Invalid negative offset

What it means

IllegalArgumentException from the OffsetAndTimestamp constructor when offset is negative. This wrapper represents a broker-resolved offset for a requested timestamp; offsets must be non-negative, so a negative value is a programming error rather than valid input.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/OffsetAndTimestamp.java:55

     * @param offset The offset
     * @param timestamp The timestamp
     * @throws IllegalArgumentException If the offset or timestamp is negative
     */
    public OffsetAndTimestamp(long offset, long timestamp) {
        this(offset, timestamp, Optional.empty());
    }

    /**
     * Constructs a new OffsetAndTimestamp with the given offset, timestamp, and leader epoch.
     *
     * @param offset The offset
     * @param timestamp The timestamp
     * @param leaderEpoch The leader epoch
     * @throws IllegalArgumentException If the offset or timestamp is negative
     */
    public OffsetAndTimestamp(long offset, long timestamp, Optional<Integer> leaderEpoch) {
        if (offset < 0)
            throw new IllegalArgumentException("Invalid negative offset");

        if (timestamp < 0)
            throw new IllegalArgumentException("Invalid negative timestamp");

        this.offset = offset;
        this.timestamp = timestamp;
        this.leaderEpoch = leaderEpoch;
    }

    /**
     * Returns the timestamp.
     *
     * @return The timestamp
     */
    public long timestamp() {
        return timestamp;
    }

View on GitHub (pinned to c31c9215e1)

Solutions

1. Do not construct OffsetAndTimestamp when offsetsForTimes returned null for a partition; propagate null instead.
2. Validate offset >= 0 before construction; if unavailable, skip or signal 'not found' upstream.
3. Fix the source producing the negative value (e.g. subtracting past zero in offset arithmetic).

Example fix

// before
OffsetAndTimestamp ot = new OffsetAndTimestamp(-1L, ts);

// after
OffsetAndTimestamp ot = brokerResult != null ? brokerResult : null;

// OffsetAndTimestamp requires offset >= 0
if (offset < 0) {
    throw new IllegalArgumentException("OffsetAndTimestamp offset must be >= 0 (got " + offset + ")");
}
new OffsetAndTimestamp(offset, timestamp, leaderEpoch);

try {
    new OffsetAndTimestamp(offset, timestamp, leaderEpoch);
} catch (IllegalArgumentException e) {
    if ("Invalid negative offset".equals(e.getMessage())) {
        // offsetsForTimes returned nothing meaningful; skip this partition
    }
    throw e;
}

When it happens

Trigger: Calling new OffsetAndTimestamp(offset, timestamp, leaderEpoch) (or the 2-arg overload) with a negative offset, typically because a caller synthesized the result instead of using offsetsForTimes output.

Common situations: Custom wrappers around offsetsForTimes that pass a sentinel offset; mapping an unfound timestamp (which should yield null, not a constructed object) into OffsetAndTimestamp; arithmetic bugs producing a negative offset.

Related errors

• Invalid negative offset
• Invalid negative timestamp
• seek offset must not be a negative number
• seek offset must not be a negative number
• Invalid value `{}` for configuration {}. The value must be e

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/13fc871015a27ce7.json. Report an issue: GitHub.