What causes InvalidStateStoreException?

Querying a state store before the KafkaStreams instance reaches RUNNING (still CREATED/REBALANCING during startup), so local stores aren't queryable yet. A rebalance moved the store/task to another instance behind the scenes (scaling instances up/down, adding/removing stream threads), so the store you held a handle to is no longer local. Internal/changelog topic can't be written: e.g. Streams auto-created a changelog with replication.factor=1 but the broker's min.insync.replicas=2, so writes fail and the task enters an error state, surfacing as 'may have migrated to another instance'. A stale store reference is used after a thread was replaced/removed (historically the queryable-store provider wasn't refreshed when threads were added/removed/replaced — KAFKA-13096).

How do I fix InvalidStateStoreException?

Wrap `streams.store(...)` in a retry loop that catches InvalidStateStoreException and waits, since store availability is inherently point-in-time: `while(true){ try { return streams.store(name, type); } catch (InvalidStateStoreException e){ Thread.sleep(100);} }`. Gate queries on state: only query when `streams.state() == RUNNING` (or use a StateListener), and re-resolve the store handle after each rebalance instead of caching it forever. Fix internal-topic durability so changelogs can actually be written: align `replication.factor` with the broker's `min.insync.replicas` (e.g. RF >= min.ISR), or let Streams use cluster defaults; for a stuck changelog you may need to delete/recreate it. On older versions hit by the thread-replacement bug, upgrade (KAFKA-13096 was fixed in 2.8.1 / 3.0.0); and prefer `SHUTDOWN_CLIENT`/`SHUTDOWN_APPLICATION` over `REPLACE_THREAD` if thread replacement leaves IQ broken.

Is InvalidStateStoreException retriable?

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

Kafka Exception `InvalidStateStoreException`

org.apache.kafka.streams.errors.InvalidStateStoreException

Non-retriable Streams

Indicates that there was a problem when trying to access a StateStore StateStore. InvalidStateStoreException is not thrown directly but only its following subclasses.

Common Causes

Querying a state store before the KafkaStreams instance reaches RUNNING (still CREATED/REBALANCING during startup), so local stores aren't queryable yet.
A rebalance moved the store/task to another instance behind the scenes (scaling instances up/down, adding/removing stream threads), so the store you held a handle to is no longer local.
Internal/changelog topic can't be written: e.g. Streams auto-created a changelog with replication.factor=1 but the broker's min.insync.replicas=2, so writes fail and the task enters an error state, surfacing as 'may have migrated to another instance'.
A stale store reference is used after a thread was replaced/removed (historically the queryable-store provider wasn't refreshed when threads were added/removed/replaced — KAFKA-13096).

Solutions

Wrap `streams.store(...)` in a retry loop that catches InvalidStateStoreException and waits, since store availability is inherently point-in-time: `while(true){ try { return streams.store(name, type); } catch (InvalidStateStoreException e){ Thread.sleep(100);} }`.
Gate queries on state: only query when `streams.state() == RUNNING` (or use a StateListener), and re-resolve the store handle after each rebalance instead of caching it forever.
Fix internal-topic durability so changelogs can actually be written: align `replication.factor` with the broker's `min.insync.replicas` (e.g. RF >= min.ISR), or let Streams use cluster defaults; for a stuck changelog you may need to delete/recreate it.
On older versions hit by the thread-replacement bug, upgrade (KAFKA-13096 was fixed in 2.8.1 / 3.0.0); and prefer `SHUTDOWN_CLIENT`/`SHUTDOWN_APPLICATION` over `REPLACE_THREAD` if thread replacement leaves IQ broken.

Example Stack Trace

org.apache.kafka.streams.errors.InvalidStateStoreException: The state store, my-key-value-store, may have migrated to another instance.
	at org.apache.kafka.streams.state.internals.StreamThreadStateStoreProvider.stores(StreamThreadStateStoreProvider.java:85)
	at org.apache.kafka.streams.state.internals.QueryableStoreProvider.getStore(QueryableStoreProvider.java:61)
	at org.apache.kafka.streams.KafkaStreams.store(KafkaStreams.java:1182)
	at com.example.streams.QueryService.lookup(QueryService.java:44)

Diagnostic Commands

kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic <application.id>-<store>-changelog   # check RF vs min.insync.replicas on the changelog

kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group <application.id>   # see if the group is stuck rebalancing

Hitting InvalidStateStoreException 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 InvalidStateStoreException

Common Causes

Solutions

Example Stack Trace

Diagnostic Commands

Related

Kafka Exception `InvalidStateStoreException`