Kafka Exception StreamsStoppedException
org.apache.kafka.streams.errors.StreamsStoppedException
Non-retriable
Streams
Indicates that Kafka Streams is in a terminating or terminal state, such as PENDING_SHUTDOWN,PENDING_ERROR,NOT_RUNNING, or ERROR. This Streams instance will need to be discarded and replaced before it can serve queries. The caller may wish to query a different instance.
Common Causes
- The instance is in a terminal/terminating state (PENDING_SHUTDOWN, PENDING_ERROR, NOT_RUNNING, or ERROR) when an Interactive Query arrives — typically after an uncaught exception killed the last thread or close() was called.
- All StreamThreads (or the global thread) died, transitioning KafkaStreams to ERROR; the instance will not recover and must be discarded and replaced before it can serve queries.
- A graceful shutdown is in progress (PENDING_SHUTDOWN) but the IQ/REST layer is still receiving and dispatching queries to the closing instance.
- A fatal startup/config problem (unwritable changelog, auth failure) drove the instance straight to ERROR so it never became queryable at all.
Solutions
- Treat this instance as dead: query a different instance — use KafkaStreams.streamsMetadataForStore / queryMetadataForKey to find a healthy host that owns the partition, per the Javadoc guidance ('the caller may wish to query a different instance').
- Have an orchestrator restart the JVM/pod when KafkaStreams.state() is ERROR/NOT_RUNNING (liveness probe on state == RUNNING); an instance in a terminal state never self-heals.
- Fix the root cause that drove it terminal: install a StreamsUncaughtExceptionHandler returning REPLACE_THREAD for transient errors so threads are replaced instead of the whole client shutting down.
- Stop routing IQ to instances not in RUNNING: gate the REST layer on the live state and remove terminal instances from your service-discovery/load-balancer pool.
Example Stack Trace
org.apache.kafka.streams.errors.StreamsStoppedException: KafkaStreams is in a terminal state and can no longer serve queries; current state is ERROR
at org.apache.kafka.streams.KafkaStreams.validateIsRunningOrRebalancing(KafkaStreams.java:1452)
at org.apache.kafka.streams.KafkaStreams.store(KafkaStreams.java:1798)
at com.example.QueryService.lookup(QueryService.java:43)Diagnostic Commands
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-app # confirm this instance's partitions were reassigned to a surviving one. This instance is terminal — restart the JVM/pod after fixing the root cause; do NOT run application-reset just to relaunch one instance (it deletes internal topics and forces a full replay).
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-app # verify partitions got reassigned to a surviving instanceRelated
Related Streams exceptions: BrokerNotFoundException · InternalTopicsAlreadySetupException · InvalidStateStoreException · InvalidStateStorePartitionException · LockException · MisconfiguredInternalTopicException · MissingInternalTopicsException · MissingSourceTopicException
Hitting
StreamsStoppedException in production? Conduktor Console gives you real-time visibility into clients, consumer groups, and broker health. Browse every Kafka exception or protocol error code.