apache/kafka · error · IllegalArgumentException

Invalid position: {} in read from {}

Error message

Invalid position: {} in read from {}

What it means

Thrown by FileRecords.availableBytes when the requested position argument is negative. availableBytes computes the readable window for slice() and sliceUnaligned(); a negative start position is meaningless because byte offsets into the segment are always non-negative. This is a programmer-error guard, not an I/O condition.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/record/internal/FileRecords.java:171

     *
     * This method is reserved for cases where offset alignment is not necessary, such as in the replication of raft
     * snapshots.
     *
     * @param position The start position to begin the read from
     * @param size The number of bytes after the start position to include
     * @return A unaligned slice of records on this message set limited based on the given position and size
     */
    public UnalignedFileRecords sliceUnaligned(int position, int size) {
        int availableBytes = availableBytes(position, size);
        return new UnalignedFileRecords(channel, this.start + position, availableBytes);
    }

    private int availableBytes(int position, int size) {
        // Cache current size in case concurrent write changes it
        int currentSizeInBytes = sizeInBytes();

        if (position < 0)
            throw new IllegalArgumentException("Invalid position: " + position + " in read from " + this);
        // position should always be relative to the start of the file hence compare with file size
        // to verify if the position is within the file.
        if (position > currentSizeInBytes)
            throw new IllegalArgumentException("Slice from position " + position + " exceeds end position of " + this);
        if (size < 0)
            throw new IllegalArgumentException("Invalid size: " + size + " in read from " + this);

        int end = this.start + position + size;
        // Handle integer overflow or if end is beyond the end of the file
        if (end < 0 || end > start + currentSizeInBytes)
            end = this.start + currentSizeInBytes;
        return end - (this.start + position);
    }

    /**
     * Append a set of records to the file. This method is not thread-safe and must be
     * protected with a lock.
     *

View on GitHub (pinned to c31c9215e1)

Solutions

  1. Inspect the caller of slice/sliceUnaligned to confirm the position is computed from non-negative offsets (e.g. searchForOffsetFromFilePosition output).
  2. Add a precondition or assertion earlier in the call chain so the negative value is caught with more context than availableBytes provides.
  3. If you see this in production logs, grep the stack trace for the fetch/replication entry point and validate the startingOffset / startingPosition arguments.

Example fix

// before: position may go negative on underflow
int pos = targetOffset - baseOffset;
FileRecords slice = records.slice(pos, size);

// after: clamp/guard against negative positions explicitly
if (pos < 0) throw new IllegalStateException("slice position negative for target=" + targetOffset);
FileRecords slice = records.slice(pos, size);
Defensive patterns

Strategy: validation

Validate before calling

if (position < 0) {
    throw new IllegalArgumentException(
        "read/slice position must be >= 0, got " + position);
}
FileRecords slice = records.slice(position, size);

Prevention

When it happens

Trigger: Calling FileRecords.slice(position, size) or sliceUnaligned(position, size) with position < 0. These are invoked during fetch response assembly, replication reads, and raft snapshot transfer when the caller computes a byte offset into a log segment.

Common situations: An upstream arithmetic underflow (e.g. subtracting a larger offset from a smaller one), an off-by-one in a custom consumer/replica path, or passing a relative position where an absolute one was expected. Rare in stock Kafka; usually surfaces from custom tooling or buggy Log/UnifiedLog refactor changes.

Related errors

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