Introduction

Kafka does not let you change a topic's replication factor with a single simple "set replicas to N" command. To change the number of replicas, you normally reassign partitions so that each partition ends up with a replica list of the desired size.

What Changing Replicas Really Means

A topic's replication factor is reflected in the replica list for each partition. So changing the topic from, for example, two replicas to three replicas means changing every partition's assigned broker list from length two to length three.

That is why the operation is really a partition reassignment problem, not just a configuration toggle.

Create a Reassignment Plan

The standard operational workflow uses the Kafka reassignment tooling.

First, create a JSON file describing which topic should move:

1{
2  "topics": [
3    { "topic": "my-topic" }
4  ],
5  "version": 1
6}

Then generate a proposal:

1kafka-reassign-partitions.sh \
2  --bootstrap-server localhost:9092 \
3  --generate \
4  --topics-to-move-json-file topics-to-move.json \
5  --broker-list "1,2,3"

Kafka prints a suggested reassignment JSON that you can edit.

Edit the Replica Lists

To increase replication factor, each partition needs a longer replica list.

1{
2  "version": 1,
3  "partitions": [
4    { "topic": "my-topic", "partition": 0, "replicas": [1, 2, 3] },
5    { "topic": "my-topic", "partition": 1, "replicas": [2, 3, 1] }
6  ]
7}

If the topic previously had only two replicas per partition, this edited plan increases it to three by assigning an additional broker to each partition.

To reduce the replication factor, do the reverse and shorten the replica lists deliberately.

Execute the Reassignment

Once the plan looks correct:

1kafka-reassign-partitions.sh \
2  --bootstrap-server localhost:9092 \
3  --execute \
4  --reassignment-json-file reassignment.json

Then verify:

1kafka-reassign-partitions.sh \
2  --bootstrap-server localhost:9092 \
3  --verify \
4  --reassignment-json-file reassignment.json

Verification matters because the reassignment may take time and can fail if brokers are unavailable or storage pressure is too high.

Practical Constraints

A replication factor cannot exceed the number of brokers available to host replicas. So a three-replica topic needs at least three suitable brokers.

You should also think about:

• broker disk capacity
• network traffic during replica catch-up
• leader placement
• maintenance windows for busy clusters

Changing replication is an operational change, not just a metadata edit.

Why Not Just Alter Topic Config

Kafka topic configs can change many settings directly, but replication factor is not just a config key. It determines physical data placement and redundancy, which is why the platform handles it through reassignment mechanics instead of a light metadata switch.

That distinction is important when explaining the process to teams: you are moving and synchronizing replicas, not only updating a number in a catalog.

Common Pitfalls

The biggest pitfall is thinking replication factor can be changed with a simple --alter command. For existing topics, the normal path is partition reassignment.

Another common mistake is editing the reassignment JSON without checking broker capacity or distribution. A technically valid plan can still create an operationally bad layout.

Developers also sometimes forget to verify the reassignment after execution. Until verification succeeds, the cluster may still be catching up or only partially finished.

Summary

• Changing a Kafka topic's replica count means changing each partition's replica assignment.
• The normal workflow is to generate, edit, execute, and verify a reassignment plan.
• Replication factor cannot exceed the number of brokers that can host replicas.
• This is a data-placement operation, not just a simple config toggle.
• Always verify the reassignment and check cluster capacity before making the change.