How to Increase Kafka Topic Partitions Safely and Why You Can't Decrease Them

After a Kafka topic is created, you can modify its configuration, such as increasing the number of partitions, using the kafka-topics.sh script with the --alter option.

bin/kafka-topics.sh --zookeeper localhost:2181/kafka \
    --alter --topic topic-config --partitions 3
WARNING: If partitions are increased for a topic that has a key,
the partition logic or ordering of the messages will be affected
Adding partitions succeeded!

bin/kafka-topics.sh --zookeeper localhost:2181/kafka \
    --describe --topic topic-config
Topic:topic-config    PartitionCount:3  ReplicationFactor:1   Configs:
Topic: topic-config    Partition:0 Leader:2    Replicas:2  Isr:2
Topic: topic-config    Partition:1 Leader:0    Replicas:0  Isr:0
Topic: topic-config    Partition:2 Leader:1    Replicas:1  Isr:1

The warning indicates that when messages contain a non‑null key, increasing partitions changes how keys are mapped to partitions, which can alter the original ordering of messages. Therefore, for key‑based topics, set the desired partition count at creation time.

Kafka only supports increasing partitions; decreasing them triggers an InvalidPartitionsException:

bin/kafka-topics.sh --zookeeper localhost:2181/kafka \
    --alter --topic topic-config --partitions 1
WARNING: If partitions are increased for a topic that has a key,
    the partition logic or ordering of the messages will be affected
Error while executing topic command : The number of partitions 
for a topic can only be increased. Topic topic-config currently
has 3 partitions, 1 would not be an increase.
org.apache.kafka.common.errors.InvalidPartitionsException:
The number of partitions for a topic can only be increased.

Reducing partitions is not supported because it would require handling messages in the removed partitions, preserving reliability, maintaining timestamps for downstream systems like Spark or Flink, and managing complex state transitions, all of which add significant code complexity and operational risk.

Instead, you can create a new topic with fewer partitions and migrate data, or adjust the replica count using the kafka-reassign-partition.sh script.