Kafka Exception StreamsNotStartedException
org.apache.kafka.streams.errors.StreamsNotStartedException
Non-retriable
Streams
Indicates that Kafka Streams is in state State CREATED and thus state stores cannot be queries yet. To query state stores, it's required to first start Kafka Streams via start(). You can retry to query the state after the state transitioned to State RUNNING.
Common Causes
- Calling KafkaStreams.store(...) for an Interactive Query before KafkaStreams.start() has been invoked, so the client is still in State CREATED.
- Querying immediately after start() in the same code path, before the client has transitioned out of CREATED into REBALANCING/RUNNING (a race in startup/bootstrapping logic).
- A REST/health endpoint exposing IQ goes live (reports 'Up') before the embedded Kafka Streams instance has been started, so the first query lands in CREATED state.
- Dependency-injection ordering (Spring/Quarkus) where the query service bean is wired and hit before the lifecycle that calls start() on the streams bean has run.
Solutions
- Always call KafkaStreams.start() before any store(...) call; gate IQ endpoints behind a check that KafkaStreams.state() != CREATED.
- Register a KafkaStreams.StateListener and only mark the service ready / route queries once the state reaches RUNNING (or at least past REBALANCING); return HTTP 503 until then.
- In a retry loop, catch StreamsNotStartedException specifically and retry after start() — per the Javadoc, 'just call start() and then retry this call'.
- Wire framework lifecycle so the streams instance is started before the IQ/health layer accepts traffic (e.g. Spring readiness probe tied to the RUNNING state, not just bean creation).
Example Stack Trace
org.apache.kafka.streams.errors.StreamsNotStartedException: KafkaStreams has not been started, you can retry after calling start()
at org.apache.kafka.streams.KafkaStreams.validateIsRunningOrRebalancing(KafkaStreams.java:1455)
at org.apache.kafka.streams.KafkaStreams.store(KafkaStreams.java:1798)
at com.example.QueryService.lookup(QueryService.java:40)Diagnostic Commands
# Gate interactive queries on lifecycle: only call store(...) once KafkaStreams.state() is RUNNING (register a StateListener); return HTTP 503 while CREATED, then retry after start().Related
Related Streams exceptions: BrokerNotFoundException · InternalTopicsAlreadySetupException · InvalidStateStoreException · InvalidStateStorePartitionException · LockException · MisconfiguredInternalTopicException · MissingInternalTopicsException · MissingSourceTopicException
Hitting
StreamsNotStartedException in production? Conduktor Console gives you real-time visibility into clients, consumer groups, and broker health. Browse every Kafka exception or protocol error code.