This is an automated email from the ASF dual-hosted git repository.
mjsax pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git
The following commit(s) were added to refs/heads/trunk by this push:
new 9a9998e496a MINOR: Update KafkaStreams.start JavaDocs (#21533)
9a9998e496a is described below
commit 9a9998e496a27ecbe509d6fb97365679734a6216
Author: Matthias J. Sax <[email protected]>
AuthorDate: Wed Feb 25 11:26:01 2026 -0800
MINOR: Update KafkaStreams.start JavaDocs (#21533)
Reviewers: Eduwer Camacaro <[email protected]>, Bill Bejeck
<[email protected]>
---
.../org/apache/kafka/streams/KafkaStreams.java | 24 ++++++++++++++++------
1 file changed, 18 insertions(+), 6 deletions(-)
diff --git a/streams/src/main/java/org/apache/kafka/streams/KafkaStreams.java
b/streams/src/main/java/org/apache/kafka/streams/KafkaStreams.java
index ec21a704837..b00623b32bb 100644
--- a/streams/src/main/java/org/apache/kafka/streams/KafkaStreams.java
+++ b/streams/src/main/java/org/apache/kafka/streams/KafkaStreams.java
@@ -1366,13 +1366,25 @@ public class KafkaStreams implements AutoCloseable {
* {@link #setUncaughtExceptionHandler(StreamsUncaughtExceptionHandler)
register an uncaught exception handler}
* before starting the {@code KafkaStreams} instance.
* <p>
- * Note, for brokers with version {@code 0.9.x} or lower, the broker
version cannot be checked.
- * There will be no error and the client will hang and retry to verify the
broker version until it
- * {@link StreamsConfig#REQUEST_TIMEOUT_MS_CONFIG times out}.
-
+ * <b>Note on broker compatibility:</b>
+ * <ul>
+ * <li>Kafka Streams 4.x requires brokers on version 2.1 or higher.
Connection attempts to
+ * older brokers will fail due to unsupported protocol versions.</li>
+ * <li>When {@link StreamsConfig#PROCESSING_GUARANTEE_CONFIG
processing.guarantee} is set to
+ * {@link StreamsConfig#EXACTLY_ONCE_V2 exactly_once_v2}, brokers
must be version 2.5 or higher.
+ * If the broker version is too old, the application will detect
this during the first rebalance
+ * and transition to {@link State#ERROR ERROR} state.</li>
+ * </ul>
+ * <p>
+ * Broker compatibility issues are typically detected asynchronously after
{@code start()} returns.
+ * Use {@link #setStateListener(StateListener)} or
+ * {@link #setUncaughtExceptionHandler(StreamsUncaughtExceptionHandler)}
to be notified of such failures.
+ *
* @throws IllegalStateException if process was already started
- * @throws StreamsException if the Kafka brokers have version 0.10.0.x or
- * if {@link
StreamsConfig#PROCESSING_GUARANTEE_CONFIG exactly-once} is enabled for pre
0.11.0.x brokers
+ * @throws StreamsException if the Kafka Streams instance has fatal error
and cannot be restarted
+ *
+ * @see #setStateListener(StateListener)
+ * @see #setUncaughtExceptionHandler(StreamsUncaughtExceptionHandler)
*/
public synchronized void start() throws IllegalStateException,
StreamsException {
if (setState(State.REBALANCING)) {
