apache/kafka · error · IllegalArgumentException

Invalid negative offset

Error message

Invalid negative offset

What it means

OffsetAndTimestamp is the result type returned by KafkaConsumer.offsetsForTimes(...) - it pairs an offset with the timestamp of the first record at or after the requested time. Its constructor validates offset >= 0 (and separately timestamp >= 0) and throws IllegalArgumentException otherwise, because the consumer API contract guarantees non-negative offsets for matched records.

Solutions

1. Return null from offsetsForTimes mappings for partitions with no match instead of constructing OffsetAndTimestamp with -1.
2. Guard offset >= 0 before constructing; use Optional<OffsetAndTimestamp> at API boundaries if you need to express absence.
3. Audit wrappers around offsetsForTimes results that reinterpret 'no match' as a sentinel.

Example fix

// before
OffsetAndTimestamp r = matched != null ? new OffsetAndTimestamp(matched.offset(), matched.timestamp(), leaderEpoch)
                                      : new OffsetAndTimestamp(-1L, -1L, leaderEpoch); // -> IllegalArgumentException

// after
OffsetAndTimestamp r = matched != null ? new OffsetAndTimestamp(matched.offset(), matched.timestamp(), leaderEpoch)
                                      : null;

if (offset < 0) return null;  // represent 'no match' as absence
return new OffsetAndTimestamp(offset, timestamp, leaderEpoch);

static boolean isResultOffset(long offset) { return offset >= 0; }

null

When it happens

Trigger: Direct construction new OffsetAndTimestamp(-1L, timestamp, leaderEpoch). Not normally reachable from offsetsForTimes because the consumer only produces OffsetAndTimestamp for matched (offset>=0) records; it appears when application code wraps/fakes results.

Common situations: Custom test fakes that build OffsetAndTimestamp with placeholder -1; mapping code that passes through an 'unmatched' marker instead of returning null/empty from offsetsForTimes.

Related errors

• Invalid negative timestamp
• Invalid negative offset
• The configured group.id should not be an empty string or…
• cannot be set when using a share group.
• Consumer is not subscribed to any topics or assigned any…

AI-assisted analysis of apache/kafka@996fb4585a (2026-08-11). Data as JSON: /api/errors/13fc871015a27ce7. Report an issue: GitHub.

Appendix: 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 996fb4585a)