Kafka Exception ProcessorStateException
org.apache.kafka.streams.errors.ProcessorStateException
Non-retriable
Streams
Indicates a processor state operation (e.g. init, put, get) has failed.
Common Causes
- RocksDB cannot open the state store directory: stale LOCK file from an unclean shutdown, the dir lives on /tmp and was partially deleted, a colon ':' in a windowed-store segment dir name on Windows, or a corrupt SST file — surfaces as 'Error opening store <name> at location ...'.
- Flush/commit failure: RocksDB throws a native RocksDBException at flush (disk full, too many open files / file-descriptor limit, IO error), wrapped as 'task [x_y] Failed to flush state store <name>'. Streams treats this as fatal and the thread dies.
- Close-ordering bug with caching enabled (e.g. TopologyTestDriver.close()): the record cache is flushed after the processor is already closed, throwing 'Failed to flush state store' caused by IllegalStateException 'The processor is already closed'.
- OS resource limits: low ulimit -n (RocksDB opens many files per store) or insufficient memory/disk causing the underlying open/put/flush to fail.
Solutions
- Point state.dir at a stable, dedicated disk (not /tmp), and on a crash delete the leftover LOCK file (or run kafka-streams-application-reset.sh + wipe local state) before restart. On a single SST corruption, reset that instance's local state and let it restore from the changelog.
- Raise OS limits: ulimit -n to tens of thousands; ensure free disk and inodes. For very wide topologies tune RocksDB via a custom RocksDBConfigSetter (cap max_open_files, block cache).
- In tests, add .withCachingDisabled() on the store (works around the TopologyTestDriver close-order issue, KAFKA-17429), and prefer Linux over Windows where the colon-in-path bug (KAFKA-6162) bites windowed stores.
- Always read the 'Caused by:' line — the wrapped RocksDBException/IOException is the real root cause; fix that (disk, fds, permissions, corruption) rather than the generic ProcessorStateException.
Example Stack Trace
org.apache.kafka.streams.errors.ProcessorStateException: task [1_0] Failed to flush state store my-counts-store
at org.apache.kafka.streams.processor.internals.ProcessorStateManager.flush(ProcessorStateManager.java:518)
at org.apache.kafka.streams.processor.internals.StreamTask.flushState(StreamTask.java:560)
at org.apache.kafka.streams.processor.internals.StreamTask.prepareCommit(StreamTask.java:402)
at org.apache.kafka.streams.processor.internals.TaskManager.commitAndFillInConsumedOffsetsAndMetadataPerTaskMap(TaskManager.java:1156)
at org.apache.kafka.streams.processor.internals.StreamThread.runOnce(StreamThread.java:953)
Caused by: org.rocksdb.RocksDBException: While open a file for appending: /var/lib/kafka-streams/my-app/1_0/my-counts-store/000123.sst: Too many open filesDiagnostic Commands
ulimit -n # RocksDB opens many files per store; bump if low (e.g. ulimit -n 100000)
df -h <state.dir>; df -i <state.dir> # check free disk and inodes on the state directory volume
ls -la <state.dir>/<application.id>/<task>/ # inspect for stale LOCK / *.sst; remove LOCK after a confirmed-dead processRelated
Related Streams exceptions: BrokerNotFoundException · InternalTopicsAlreadySetupException · InvalidStateStoreException · InvalidStateStorePartitionException · LockException · MisconfiguredInternalTopicException · MissingInternalTopicsException · MissingSourceTopicException
Hitting
ProcessorStateException in production? Conduktor Console gives you real-time visibility into clients, consumer groups, and broker health. Browse every Kafka exception or protocol error code.