apache/kafka · error · IllegalStateException

The partition {} does not have a beginning offset.

Error message

The partition {} does not have a beginning offset.

What it means

Thrown by MockConsumer.beginningOffsets when a requested partition has no entry in the mock's beginningOffsets map. MockConsumer does not compute offsets from a broker; the test must seed them via updateBeginningOffsets (or the equivalent set method). Asking for an unseeded partition is a test setup bug.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/MockConsumer.java:645

    }

    @Override
    public synchronized Map<TopicPartition, OffsetAndTimestamp> offsetsForTimes(Map<TopicPartition, Long> timestampsToSearch) {
        throw new UnsupportedOperationException("Not implemented yet.");
    }

    @Override
    public synchronized Map<TopicPartition, Long> beginningOffsets(Collection<TopicPartition> partitions) {
        if (offsetsException != null) {
            RuntimeException exception = this.offsetsException;
            this.offsetsException = null;
            throw exception;
        }
        Map<TopicPartition, Long> result = new HashMap<>();
        for (TopicPartition tp : partitions) {
            Long beginningOffset = beginningOffsets.get(tp);
            if (beginningOffset == null)
                throw new IllegalStateException("The partition " + tp + " does not have a beginning offset.");
            result.put(tp, beginningOffset);
        }
        return result;
    }

    @Override
    public synchronized Map<TopicPartition, Long> endOffsets(Collection<TopicPartition> partitions) {
        if (offsetsException != null) {
            RuntimeException exception = this.offsetsException;
            this.offsetsException = null;
            throw exception;
        }
        Map<TopicPartition, Long> result = new HashMap<>();
        for (TopicPartition tp : partitions) {
            Long endOffset = endOffsets.get(tp);
            if (endOffset == null)
                throw new IllegalStateException("The partition " + tp + " does not have an end offset.");
            result.put(tp, endOffset);

View on GitHub (pinned to 996fb4585a)

Solutions

1. Call mock.updateBeginningOffsets(Map.of(tp, 0L)) for every partition the code under test will query.
2. Derive partitions in the seed map from the same constants used elsewhere in the test.
3. Use a helper that seeds both beginning and end offsets for the full assignment.

Example fix

// before
mock.assign(Set.of(tp));
Long beg = mock.beginningOffsets(Set.of(tp)).get(tp); // throws

// after
mock.assign(Set.of(tp));
mock.updateBeginningOffsets(Map.of(tp, 0L));
Long beg = mock.beginningOffsets(Set.of(tp)).get(tp);

Set<TopicPartition> missing = partitions.stream()
    .filter(tp -> !seededBeginningOffsets.containsKey(tp)).collect(Collectors.toSet());
if (!missing.isEmpty()) mockConsumer.updateBeginningOffsets(
    missing.stream().collect(Collectors.toMap(tp -> tp, tp -> 0L)));
return mockConsumer.beginningOffsets(partitions);

static boolean allBeginningSeeded(MockConsumer<?,?> m, Collection<TopicPartition> tps) {
    // expose a known-seed set in the test; verify it covers tps
    return knownBeginningSeed.containsAll(tps);
}

try {
    return mockConsumer.beginningOffsets(partitions);
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("does not have a beginning offset")) {
        mockConsumer.updateBeginningOffsets(partitions.stream().collect(Collectors.toMap(tp -> tp, tp -> 0L)));
        return mockConsumer.beginningOffsets(partitions);
    }
    throw e;
}

When it happens

Trigger: Calling beginningOffsets(tp) without first updateBeginningOffsets(Map.of(tp, 0L)); partition name/number mismatch between seed and query; calling beginningOffsets for partitions never assigned.

Common situations: Test scaffolding that seeds only some partitions; refactor that added partitions without updating the seed; tests using positional logic that derives partitions not present in the seed map.

Related errors

• You can only check the position for partitions assigned to t
• The partition {} does not have an end offset.
• MockConsumer didn't have beginning offset specified, but tri
• Cannot lose partitions that are not currently assigned: {not
• Cannot add records for a partition that is not assigned to t

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