What causes UnknownStateStoreException?

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).

How do I fix UnknownStateStoreException?

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. >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.

Is UnknownStateStoreException retriable?

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

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.

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 queries

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.

Kafka Exception UnknownStateStoreException

Common Causes

Solutions

Example Stack Trace

Diagnostic Commands

Related

Kafka Exception `UnknownStateStoreException`