What causes StateStoreMigratedException?

A rebalance moved the active task (and its state store partition) from this instance to another instance while an Interactive Query was in flight, so the local store reference is now stale even though KafkaStreams.State is RUNNING or REBALANCING. Scaling the application up or down (adding/removing instances or stream threads) reassigns partitions; the store you previously resolved via KafkaStreams.store(...) now lives elsewhere and the cached handle must be re-discovered. Caching a StateStore reference and reusing it across queries instead of re-fetching it before each query, so the handle survives past the rebalance that relocated it (the exception is the framework telling you to re-discover, not a fatal error). On Kafka Streams StreamThread-2 swap on broker failure), QueryableStoreProvider failed to update and the store stayed permanently unqueryable with this message even though processing continued.

How do I fix StateStoreMigratedException?

Never cache the store handle: re-resolve it inside a retry loop right before each query, e.g. `while(true){ try { return streams.store(StoreQueryParameters.fromNameAndType(name, type)); } catch (InvalidStateStoreException e) { Thread.sleep(100); } }` and re-fetch metadata so you route to the new owning instance. Use KafkaStreams.queryMetadataForKey(store, key, serializer) (or KafkaStreams.streamsMetadataForStore) on every query to find which instance currently owns the key's partition, then route the IQ to that host; a local retry loop will never succeed if the key genuinely migrated off this node. If you can tolerate slightly stale data, pass StoreQueryParameters with enableStaleStores() so reads are served from standby/restoring replicas during migration instead of throwing. Upgrade to Kafka Streams >= 2.8.1 / 3.0.0 to pick up the KAFKA-13096 fix if the store becomes permanently unqueryable after a thread is replaced (the symptom is the exact same message but it never clears on retry).

Is StateStoreMigratedException retriable?

No — StateStoreMigratedException is not retriable. Retrying the same call will not help; the underlying cause must be fixed first.

Kafka Exception `StateStoreMigratedException`

org.apache.kafka.streams.errors.StateStoreMigratedException

Non-retriable Streams

Indicates that the state store being queried is closed although the Kafka Streams state is RUNNING RUNNING or REBALANCING REBALANCING. This could happen because the store moved to some other instance during a rebalance so rediscovery of the state store is required before retrying.

Common Causes

A rebalance moved the active task (and its state store partition) from this instance to another instance while an Interactive Query was in flight, so the local store reference is now stale even though KafkaStreams.State is RUNNING or REBALANCING.
Scaling the application up or down (adding/removing instances or stream threads) reassigns partitions; the store you previously resolved via KafkaStreams.store(...) now lives elsewhere and the cached handle must be re-discovered.
Caching a StateStore reference and reusing it across queries instead of re-fetching it before each query, so the handle survives past the rebalance that relocated it (the exception is the framework telling you to re-discover, not a fatal error).
On Kafka Streams <= 2.8.0, KAFKA-13096: after a thread was added/removed/replaced (e.g. a StreamThread-1 -> StreamThread-2 swap on broker failure), QueryableStoreProvider failed to update and the store stayed permanently unqueryable with this message even though processing continued.

Solutions

Never cache the store handle: re-resolve it inside a retry loop right before each query, e.g. `while(true){ try { return streams.store(StoreQueryParameters.fromNameAndType(name, type)); } catch (InvalidStateStoreException e) { Thread.sleep(100); } }` and re-fetch metadata so you route to the new owning instance.
Use KafkaStreams.queryMetadataForKey(store, key, serializer) (or KafkaStreams.streamsMetadataForStore) on every query to find which instance currently owns the key's partition, then route the IQ to that host; a local retry loop will never succeed if the key genuinely migrated off this node.
If you can tolerate slightly stale data, pass StoreQueryParameters with enableStaleStores() so reads are served from standby/restoring replicas during migration instead of throwing.
Upgrade to Kafka Streams >= 2.8.1 / 3.0.0 to pick up the KAFKA-13096 fix if the store becomes permanently unqueryable after a thread is replaced (the symptom is the exact same message but it never clears on retry).

Example Stack Trace

org.apache.kafka.streams.errors.StateStoreMigratedException: The state store, word-counts-store, may have migrated to another instance.
	at org.apache.kafka.streams.state.internals.StreamThreadStateStoreProvider.stores(StreamThreadStateStoreProvider.java:80)
	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-streams-application-reset.sh --application-id my-app --bootstrap-server localhost:9092 --to-earliest   # only if state is genuinely corrupt; not needed for a normal migration

kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-app   # check rebalance churn / partition reassignment that triggered the migration

Hitting StateStoreMigratedException in production? Conduktor Console gives you real-time visibility into clients, consumer groups, and broker health. Browse every Kafka exception or protocol error code.

Kafka Exception StateStoreMigratedException

Common Causes

Solutions

Example Stack Trace

Diagnostic Commands

Related

Kafka Exception `StateStoreMigratedException`