Kafka Exception UnknownStateStoreException
org.apache.kafka.streams.errors.UnknownStateStoreException
Non-retriable
Streams
Indicates that the state store being queried is unknown, i.e., the state store does either not exist in your topology or it is not queryable.
Editorial scenario: verification date unknown. Verify against the installed version before changing data or configuration.
Common Causes
- Querying a store name that was never registered in the topology (typo, wrong store name, or a store that exists in a different KafkaStreams instance/topology): KafkaStreams#store() throws 'Cannot get state store X because no such store is registered in the topology.'
- Querying a store that exists but is not queryable: e.g. a store that was not named via `Materialized.as(...)` so it has no queryable name, an internal store, or asking for the wrong `QueryableStoreType` (key-value vs window vs session).
- Spring Cloud Stream multi-binding regression (3.1+): a behavior change in KafkaStreams#store(StoreQueryParameters) made it scan ALL stores in the topology, and because the SCS binder adds every StoreBuilder bean to every StreamsBuilder, the lookup resolves against the wrong KafkaStreams instance and fails for stores owned by another binding (spring-cloud-stream #2445, #2523).
- Looking up the store before the topology is fully initialized so the registry doesn't yet know the store (distinct from the transient StreamsNotStartedException, which is about the app not being in RUNNING).
Solutions
- Verify the store actually exists: print `streams.metadataForAllStreamsClients()`/`topology.describe()` and confirm the exact store name matches what you pass to `StoreQueryParameters.fromNameAndType(name, type)`.
- Materialize the store so it is queryable: `builder.table(topic, Materialized.<K,V,KeyValueStore<Bytes,byte[]>>as("my-store"))` (or `.count(Materialized.as("..."))`), and query with the matching `QueryableStoreTypes` (keyValueStore / windowStore / sessionStore).
- On Spring Cloud Stream with multiple Kafka Streams functions, upgrade past the fix PRs (#2447 / #2528 / #2534) and/or query via `InteractiveQueryService.getQueryableStore(name, type)` against the correct binding so each app resolves its own store rather than scanning all StoreBuilder beans.
- Distinguish from siblings: UnknownStateStoreException means the store name is wrong/unregistered (a code/config bug, not retriable); StreamsNotStartedException / 'may have migrated to another instance' (InvalidStateStoreException) are transient — retry those, but fix the name for UnknownStateStoreException.
Example Stack Trace
org.apache.kafka.streams.errors.UnknownStateStoreException: Cannot get state store my-counts-store because no such store is registered in the topology.
at org.apache.kafka.streams.state.internals.QueryableStoreProvider.getStore(QueryableStoreProvider.java:65)
at org.apache.kafka.streams.KafkaStreams.store(KafkaStreams.java:1903)
at com.example.QueryService.count(QueryService.java:58)
at com.example.QueryService.lambda$queryEndpoint$0(QueryService.java:41)Diagnostic Commands
System.out.println(builder.build().describe()); # confirm the store appears under a Processor's 'Stores:' line with the exact name you query
curl http://localhost:8080/actuator/health # (Spring) ensure the Streams binding is up before issuing interactive queriesRelated
Related Streams exceptions: BrokerNotFoundException · InternalTopicsAlreadySetupException · InvalidStateStoreException · InvalidStateStorePartitionException · LockException · MisconfiguredInternalTopicException · MissingInternalTopicsException · MissingSourceTopicException
Hitting
UnknownStateStoreException in production? Conduktor Console gives you real-time visibility into clients, consumer groups, and broker health. Browse every Kafka exception or protocol error code.