What causes "Invalid negative timestamp" in apache/kafka?

Use 0L (CreateTime.NO_TIMESTAMP) or skip construction when no timestamp is available.

apache/kafka · error · java.lang.IllegalArgumentException

Invalid negative timestamp

Error message

Invalid negative timestamp

What it means

IllegalArgumentException from the OffsetAndTimestamp constructor when timestamp is negative. The wrapper pairs a found offset with its event timestamp; negative timestamps are not valid message times (NO_TIMESTAMP is represented as 0, not negative), so construction fails fast.

Source

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

     */
    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;
    }

    /**
     * Returns the offset.
     *

View on GitHub (pinned to c31c9215e1)

Solutions

Use 0L (CreateTime.NO_TIMESTAMP) or skip construction when no timestamp is available.
Clamp or guard: only construct OffsetAndTimestamp when timestamp >= 0.
Fix the upstream source so its 'missing' value is not a negative long.

Example fix

// before
new OffsetAndTimestamp(offset, -1L);

// after
if (ts < 0) ts = 0L; // or skip creating the instance
new OffsetAndTimestamp(offset, ts);

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
    new OffsetAndTimestamp(offset, timestamp, leaderEpoch);
} catch (IllegalArgumentException e) {
    if ("Invalid negative timestamp".equals(e.getMessage())) {
        // use NO_TIMESTAMP (default -1/-1) handling: skip or fall back to wall-clock time
    }
    throw e;
}

Prevention

Use TimestampType.NO_TIMESTAMP_TYPE semantics deliberately; do not pass -1 as a real timestamp.
When sourcing timestamps from user input or external clocks, clamp to System.currentTimeMillis() >= 0.
Document any sentinel (e.g. -1) at the boundary and translate it before constructing OffsetAndTimestamp.

When it happens

Trigger: Calling new OffsetAndTimestamp(offset, timestamp, ...) with a negative timestamp, e.g. passing an error/sentinel time or a clock that underflowed.

Common situations: Translating a missing timestamp as -1 instead of 0/absent; arithmetic on message timestamps that goes negative; bridging from a system whose "no-timestamp" marker is negative.

Related errors

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