t8y2/dbx · error · IllegalArgumentException

Kafka partition ${partition} does not exist for topic '${top

Error message

Kafka partition ${partition} does not exist for topic '${topic}'. Available partitions: ${available}

What it means

resolvePeekPartitions validates that a user-supplied partition exists on the target topic before constructing a TopicPartition. If the partition is not in the topic's available partition list, the driver throws this IllegalArgumentException listing the valid partitions. This catches typos and stale partition counts before a consumer fetch fails confusingly.

Source

Thrown at agents/drivers/kafka/src/main/java/com/dbx/agent/kafka/KafkaAgent.java:2080

        String topic,
        Integer partition,
        Duration timeout
    ) {
        List<PartitionInfo> infos = consumer.partitionsFor(topic, timeout);
        if (infos == null || infos.isEmpty()) {
            return Collections.emptyList();
        }
        List<Integer> available = infos.stream().map(PartitionInfo::partition).collect(Collectors.toList());
        return resolvePeekPartitions(topic, partition, available);
    }

    static List<TopicPartition> resolvePeekPartitions(String topic, Integer partition, List<Integer> availablePartitions) {
        if (partition != null) {
            if (availablePartitions == null || !availablePartitions.contains(partition)) {
                String available = availablePartitions == null || availablePartitions.isEmpty()
                    ? "none"
                    : availablePartitions.stream().sorted().map(String::valueOf).collect(Collectors.joining(", "));
                throw new IllegalArgumentException(
                    "Kafka partition " + partition + " does not exist for topic '" + topic
                        + "'. Available partitions: " + available
                );
            }
            return Collections.singletonList(new TopicPartition(topic, partition));
        }
        if (availablePartitions == null || availablePartitions.isEmpty()) {
            return Collections.emptyList();
        }
        return availablePartitions.stream()
            .sorted()
            .map(id -> new TopicPartition(topic, id))
            .collect(Collectors.toList());
    }

    enum PeekStartPosition {
        EARLIEST,
        LATEST,

View on GitHub (pinned to c0390bff16)

Solutions

1. Query topic partitions first (describeTopics) and pick a partition from the returned list.
2. Omit the partition parameter to peek across all partitions instead of pinning one.
3. Verify the topic name and environment; the available partitions in the error message show what is valid.

Example fix

// before
agent.peek(conn, "orders", /* partition */ 3); // topic has 2 partitions

// after
List<Integer> parts = agent.listPartitions(conn, "orders");
agent.peek(conn, "orders", parts.get(0));

List<Integer> available = agent.listPartitions(conn, topic); // or describeTopics
if (partition != null && !available.contains(partition)) {
    throw new IllegalArgumentException("partition " + partition + " not in " + available);
}

boolean partitionExists(int partition, List<Integer> available) {
    return available != null && available.contains(partition);
}

try {
    return agent.peek(conn, topic, partition);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("does not exist for topic")) {
        return agent.peek(conn, topic, null); // fall back to all partitions
    } else throw e;
}

When it happens

Trigger: Calling the peek API with partition=N where the topic has fewer than N+1 partitions, the topic does not exist (available partitions resolves to 'none'), or availablePartitions could not be fetched (null).

Common situations: Hard-coding partition 1 on a topic that only has one partition (0); partition count was reduced after topic re-creation; pointing at the wrong environment/topic name that has different partitioning; cluster metadata unavailable.

Related errors

• partition must be non-negative
• offsets must be an array
• Peek message count must be between 1 and " + MAX_PEEK_MESSAG
• ${name} must be a positive integer
• Unsupported peek startPosition: ${value}

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/1ff55e1918f564a8. Report an issue: GitHub.