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 e37634fe8ddaf..0549501cde20e 100644
--- a/streams/src/main/java/org/apache/kafka/streams/KafkaStreams.java
+++ b/streams/src/main/java/org/apache/kafka/streams/KafkaStreams.java
@@ -241,6 +241,11 @@ public class KafkaStreams implements AutoCloseable {
      *     Any state except NOT_RUNNING, PENDING_ERROR or ERROR can go to PENDING_SHUTDOWN (whenever close is called)
      *   </li>
      *   <li>
+     *     PENDING_SHUTDOWN and PENDING_ERROR are transitory states where the Streams application gracefully closes
+     *     its existing resources before transitioning into their corresponding terminal states. These states are
+     *     not recoverable, and only a restart would get an application back to the RUNNING state.
+     *   </li>
+     *   <li>
      *     Of special importance: If the global stream thread dies, or all stream threads die (or both) then
      *     the instance will be in the ERROR state. The user will not need to close it.
      *   </li>