Kafka Exception StateStoreNotAvailableException
org.apache.kafka.streams.errors.StateStoreNotAvailableException
Non-retriable
Streams
Indicates that the state store being queried is already closed. This could happen when Kafka Streams is in PENDING_SHUTDOWN PENDING_SHUTDOWN or NOT_RUNNING NOT_RUNNING or ERROR ERROR state.
Common Causes
- A StreamThread (or all threads, or the global thread) died from an uncaught exception, so KafkaStreams transitioned to ERROR / PENDING_SHUTDOWN / NOT_RUNNING; querying the now-closed store throws this rather than a transient migration error.
- An internal/changelog topic could not be written: e.g. its replication factor is 1 but the broker enforces min.insync.replicas=2, so the changelog is permanently unwritable, restoration fails, and the Streams client enters ERROR (classic Strimzi topic-store symptom).
- Application shutdown was requested (KafkaStreams.close()) while IQ traffic was still arriving, so the store closed underneath an in-flight query.
- A fatal/non-retriable error (auth failure, serialization poison pill with default handler, OutOfMemoryError) killed the last live thread and put the whole instance into a terminal state from which stores never reopen.
Solutions
- Register a StreamsUncaughtExceptionHandler that returns REPLACE_THREAD for transient errors so a dead thread is replaced and stores reopen, instead of letting the instance fall into ERROR (default since Kafka 2.8 is SHUTDOWN_CLIENT).
- Set the changelog/internal-topic replication factor compatible with the broker's min.insync.replicas (e.g. replication.factor=3 when min.insync.replicas=2) via StreamsConfig, so changelogs are writable and restoration completes.
- Check KafkaStreams.state() before querying and treat ERROR/NOT_RUNNING as 'discard this instance' — route the query to a healthy replica via queryMetadataForKey rather than retrying the dead one.
- Add liveness/readiness probes on KafkaStreams.State (RUNNING) so an orchestrator (k8s) restarts an instance stuck in ERROR; a state in ERROR will never recover on its own and must be replaced.
Example Stack Trace
org.apache.kafka.streams.errors.StateStoreNotAvailableException: State store is not available anymore and may have been migrated to another instance; it cannot be queried.
at org.apache.kafka.streams.state.internals.StreamThreadStateStoreProvider.stores(StreamThreadStateStoreProvider.java:70)
at org.apache.kafka.streams.state.internals.QueryableStoreProvider.getStore(QueryableStoreProvider.java:75)
at org.apache.kafka.streams.KafkaStreams.store(KafkaStreams.java:1804)
at com.example.QueryService.lookup(QueryService.java:42)Diagnostic Commands
kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic my-app-store-changelog # check replication factor vs min.insync.replicas
kafka-streams-application-reset.sh --application-id my-app --bootstrap-server localhost:9092 # before restarting an instance whose local state is suspectRelated
Related Streams exceptions: BrokerNotFoundException · InternalTopicsAlreadySetupException · InvalidStateStoreException · InvalidStateStorePartitionException · LockException · MisconfiguredInternalTopicException · MissingInternalTopicsException · MissingSourceTopicException
Hitting
StateStoreNotAvailableException in production? Conduktor Console gives you real-time visibility into clients, consumer groups, and broker health. Browse every Kafka exception or protocol error code.