(kafka-site) branch markdown updated: Add warning about KAFKA-20254 migration bug to 4.2 docs (#824)

[lu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

lucasbru pushed a commit to branch markdown
in repository https://gitbox.apache.org/repos/asf/kafka-site.git


The following commit(s) were added to refs/heads/markdown by this push:
     new a975f44cfd Add warning about KAFKA-20254 migration bug to 4.2 docs (#824)
a975f44cfd is described below

commit a975f44cfd59edc239b12c558ef3841a9d115494
Author: Lucas Brutschy <lb...@confluent.io>
AuthorDate: Mon Mar 9 14:20:05 2026 +0100

    Add warning about KAFKA-20254 migration bug to 4.2 docs (#824)
    
    A critical broker-side bug in the offline migration code (KAFKA-20254) affects migrations from classic to streams groups in 4.2.0. This adds warnings to the upgrade notes, streams upgrade guide, and streams rebalance protocol documentation advising users to wait for a later release before migrating.
---
 content/en/42/getting-started/upgrade.md                            | 2 +-
 content/en/42/streams/developer-guide/streams-rebalance-protocol.md | 2 ++
 content/en/42/streams/upgrade-guide.md                              | 2 ++
 3 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/content/en/42/getting-started/upgrade.md b/content/en/42/getting-started/upgrade.md
index 6b40e8cb70..83ab8e0a31 100644
--- a/content/en/42/getting-started/upgrade.md
+++ b/content/en/42/getting-started/upgrade.md
@@ -34,7 +34,7 @@ type: docs
 
   * The `--max-partition-memory-bytes` option in `kafka-console-producer` is deprecated and will be removed in Kafka 5.0. Please use `--batch-size` instead. 
   * Queues for Kafka ([KIP-932](https://cwiki.apache.org/confluence/x/4hA0Dw)) is production-ready in Apache Kafka 4.2. This feature introduces a new kind of group called share groups, as an alternative to consumer groups. Consumers in a share group cooperatively consume records from topics, without assigning each partition to just one consumer. Share groups also introduce per-record acknowledgement and counting of delivery attempts. Use share groups in cases where records are processed  [...]
-  * The Streams Rebalance Protocol ([KIP-1071](https://cwiki.apache.org/confluence/display/KAFKA/KIP-1071%3A+Streams+Rebalance+Protocol)) is now production-ready for its core feature set. This broker-driven rebalancing system designed specifically for Kafka Streams applications provides faster, more stable rebalances and better observability. For more information about the supported feature set, usage, and migration, please refer to the [Streams developer guide](/{version}/streams/develo [...]
+  * The Streams Rebalance Protocol ([KIP-1071](https://cwiki.apache.org/confluence/display/KAFKA/KIP-1071%3A+Streams+Rebalance+Protocol)) is now production-ready for its core feature set. This broker-driven rebalancing system designed specifically for Kafka Streams applications provides faster, more stable rebalances and better observability. For more information about the supported feature set, usage, and migration, please refer to the [Streams developer guide](/{version}/streams/develo [...]
   * The `org.apache.kafka.common.header.internals.RecordHeader` class has been updated to be read thread-safe. See [KIP-1205](https://cwiki.apache.org/confluence/x/nYmhFg) for details. In other words, each individual `Header` object within a `ConsumerRecord`'s `headers` can now be safely read from multiple threads concurrently. 
   * The `org.apache.kafka.disallowed.login.modules` config was deprecated. Please use the `org.apache.kafka.allowed.login.modules` instead. 
   * The `remote.log.manager.thread.pool.size` config was deprecated. Please use the `remote.log.manager.follower.thread.pool.size` instead. 
diff --git a/content/en/42/streams/developer-guide/streams-rebalance-protocol.md b/content/en/42/streams/developer-guide/streams-rebalance-protocol.md
index 0b56d41134..33800ebc17 100644
--- a/content/en/42/streams/developer-guide/streams-rebalance-protocol.md
+++ b/content/en/42/streams/developer-guide/streams-rebalance-protocol.md
@@ -253,3 +253,5 @@ The only broker-side group data that will be preserved are the committed offsets
 Similarly, you can convert a streams group back to a classic group by following the same process but setting `group.protocol=classic`.
 
 **Warning:** Online migration (migrating while the application is running) is not available in this version. Plan for a maintenance window when migrating between protocols.
+
+**Warning:** Due to a critical broker-side bug in the offline migration code ([KAFKA-20254](https://issues.apache.org/jira/browse/KAFKA-20254)), we recommend against doing migrations from classic to streams groups in 4.2.0. Newly created streams groups are not impacted. Users planning to migrate should upgrade their brokers to a later release that includes the fix.
diff --git a/content/en/42/streams/upgrade-guide.md b/content/en/42/streams/upgrade-guide.md
index bec8f25d34..a201d2a108 100644
--- a/content/en/42/streams/upgrade-guide.md
+++ b/content/en/42/streams/upgrade-guide.md
@@ -72,6 +72,8 @@ This release marks the General Availability for the core functionality detailed
 For more information about the feature set, design, usage and migration, 
 please refer to the [developer guide](/{version}/streams/developer-guide/streams-rebalance-protocol).
 
+**Note:** Due to a critical broker-side bug in the offline migration code ([KAFKA-20254](https://issues.apache.org/jira/browse/KAFKA-20254)), we recommend against doing migrations from classic to streams groups in 4.2.0. Newly created streams groups are not impacted. Users planning to migrate should upgrade their brokers to a later release that includes the fix.
+
 ### Other changes
 
 Kafka Streams now supports Dead Letter Queue (DLQ). A new config `errors.deadletterqueue.topic.name` allows to specify the name of the DLQ topic. When set and `DefaultProductionExceptionHandler` is used, records that cause exceptions will be forwarded to the DLQ topic. If a custom exception handler is used, it is up to the custom handler to build DLQ records to send, hence, depending on the implementation, the `errors.deadletterqueue.topic.name` configuration may be ignored. `org.apache. [...]