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.
Editorial scenario: verification date unknown. Verify against the installed version before changing data or configuration.
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
- Resolve the store through the current query API and retry transient unavailability with a bounded backoff and deadline. Check Streams lifecycle state and fail clearly on terminal states; do not use an infinite sleep/retry loop.
- 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.
- Check internal-topic replicas, minimum ISR and permissions. Recover with the documented application recovery procedure; deleting or recreating a changelog can destroy the only recoverable state.
- 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 rebalancingRelated
Related Streams exceptions: BrokerNotFoundException · InternalTopicsAlreadySetupException · InvalidStateStorePartitionException · LockException · MisconfiguredInternalTopicException · MissingInternalTopicsException · MissingSourceTopicException · ProcessorStateException
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.