apache/beam · error · IllegalStateException

First entry is null when initial sequence is set.

Error message

First entry is null when initial sequence is set.

What it means

SequenceRangeAccumulator.largestContinuousRange() checks that when initialSequence is set, at least one data entry exists. Hitting this IllegalStateException means the accumulator claims an initial sequence was seen but its internal TreeMap is empty — an impossible state that signals corrupted accumulator state (e.g. data was dropped or deserialized incorrectly).

Solutions

1. Fix the accumulator codec (encode/decode) so data entries are preserved along with initialSequence.
2. Reset initialSequence to null whenever data is cleared, keeping the invariant in sync.
3. Avoid external mutation; use the public add()/merge() API only.
4. If reachable from a library bug, upgrade the beam extensions/ordered artifact to a fixed version.

Example fix

// before
acc.data.clear(); // initialSequence left non-null
// after
acc.data.clear();
acc.initialSequence = null; // restore invariant

if (acc.getInitialSequence() != null && acc.isEmpty()) {
  throw new IllegalStateException("corrupt accumulator: initialSequence set but no data entries");
}

static boolean isConsistent(SequenceRangeAccumulator acc) {
  return acc.getInitialSequence() == null || !acc.isEmpty();
}

try {
  ContiguousSequenceRange r = acc.largestContinuousRange();
} catch (IllegalStateException e) {
  if (e.getMessage().contains("First entry is null")) {
    throw new IllegalStateException("accumulator data lost in codec/merge; fix encode/decode", e);
  }
  throw e;
}

When it happens

Trigger: Calling result()/largestContinuousRange() on an accumulator where initialSequence != null but data is empty — usually after a faulty custom codec/clone of the accumulator, or external mutation of accumulator fields.

Common situations: Custom accumulation/encoding of accumulators losing the data map but keeping initialSequence; reflection-based mutation in tests; combining logic that clears data without resetting initialSequence.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• There are different initial sequences detected
• Two accumulators contain different initial sequences
• {element}
• Failed to optimize AddInput for combiner
• Failed to optimize CreateAccumulator for combiner

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/55411f2d52eae7ef. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/extensions/ordered/src/main/java/org/apache/beam/sdk/extensions/ordered/combiner/SequenceRangeAccumulator.java:135

        && lowerRange.getValue().getLeft() > sequence) {
      // The sequence is in the middle of the range. Adjust it.
      data.remove(lowerRange.getKey());
      data.put(
          sequence,
          Pair.of(
              lowerRange.getValue().getKey(), max(timestamp, lowerRange.getValue().getValue())));
    }
    data.subMap(Long.MIN_VALUE, sequence).clear();
  }

  public ContiguousSequenceRange largestContinuousRange() {
    if (initialSequence == null) {
      return ContiguousSequenceRange.EMPTY;
    }

    Entry<Long, Pair<Long, Instant>> firstEntry = data.firstEntry();
    if (firstEntry == null) {
      throw new IllegalStateException("First entry is null when initial sequence is set.");
    }
    Long start = firstEntry.getKey();
    Long end = firstEntry.getValue().getLeft();
    Instant latestTimestamp = firstEntry.getValue().getRight();
    // Upper bound is inclusive, but the ContiguousSequenceRange's end is exclusive.
    // The numeric overflow is prevented by dropping the value of Long.MAX.
    return ContiguousSequenceRange.of(start, end + 1, latestTimestamp);
  }

  public int numberOfRanges() {
    return data.size();
  }

  public void merge(SequenceRangeAccumulator another) {
    if (this.initialSequence != null
        && another.initialSequence != null
        && !this.initialSequence.equals(another.initialSequence)) {
      throw new IllegalStateException(

View on GitHub (pinned to 12126d8942)