What causes TaskIdFormatException?

Corrupted or hand-edited Kafka Streams local state: TaskId.parse() reads task directory names under `state.dir/ /` (e.g. `0_3`), and a directory or `.checkpoint`/lock file name that does not match the expected ` _ ` (or, since 3.0, the optional ` __ _ `) layout makes the parse fail. Restoring state produced by an incompatible Streams version: older releases serialized TaskId differently, so reading a checkpoint or assignment blob from a mismatched version yields an unparseable string. Custom tooling or tests calling `TaskId.parse(String)` directly with a malformed value (e.g. `"hello_world"`, a UUID, or a topic name) instead of the `digits_digits` form. A truncated/garbled task id arriving over the wire in the subscription/assignment userdata (e.g. partial write, encoding mismatch) so the partition assignor cannot decode the task set.

How do I fix TaskIdFormatException?

Never hand-edit the Streams state directory. If a task folder is corrupt, stop the instance and run `kafka-streams-application-reset.sh` then wipe `state.dir` so Streams rebuilds clean directories with valid names. Keep all application instances and the client library on the same Kafka Streams version during a rolling upgrade; reset/clean local state when crossing a major version that changed TaskId serialization (e.g. 2.x -> 3.x). When parsing task ids in your own code/tests, pass exactly `subtopology + "_" + partition` (e.g. `"0_0"`); use `new TaskId(subtopology, partition)` to construct and `taskId.toString()` to serialize rather than building the string by hand. If the exception surfaces during assignment, restart the affected instances with a clean local state dir so the assignor regenerates valid userdata, and check for disk/encoding issues on the state volume.

Is TaskIdFormatException retriable?

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

Kafka Exception `TaskIdFormatException`

org.apache.kafka.streams.errors.TaskIdFormatException

Non-retriable Streams

Indicates a run time error incurred while trying parse the TaskId task id from the read string.

Common Causes

Corrupted or hand-edited Kafka Streams local state: TaskId.parse() reads task directory names under `state.dir/<application.id>/` (e.g. `0_3`), and a directory or `.checkpoint`/lock file name that does not match the expected `<subtopologyId>_<partition>` (or, since 3.0, the optional `<namedTopology>__<subtopologyId>_<partition>`) layout makes the parse fail.
Restoring state produced by an incompatible Streams version: older releases serialized TaskId differently, so reading a checkpoint or assignment blob from a mismatched version yields an unparseable string.
Custom tooling or tests calling `TaskId.parse(String)` directly with a malformed value (e.g. `"hello_world"`, a UUID, or a topic name) instead of the `digits_digits` form.
A truncated/garbled task id arriving over the wire in the subscription/assignment userdata (e.g. partial write, encoding mismatch) so the partition assignor cannot decode the task set.

Solutions

Never hand-edit the Streams state directory. If a task folder is corrupt, stop the instance and run `kafka-streams-application-reset.sh` then wipe `state.dir` so Streams rebuilds clean directories with valid names.
Keep all application instances and the client library on the same Kafka Streams version during a rolling upgrade; reset/clean local state when crossing a major version that changed TaskId serialization (e.g. 2.x -> 3.x).
When parsing task ids in your own code/tests, pass exactly `subtopology + "_" + partition` (e.g. `"0_0"`); use `new TaskId(subtopology, partition)` to construct and `taskId.toString()` to serialize rather than building the string by hand.
If the exception surfaces during assignment, restart the affected instances with a clean local state dir so the assignor regenerates valid userdata, and check for disk/encoding issues on the state volume.

Example Stack Trace

org.apache.kafka.streams.errors.TaskIdFormatException: Task id cannot be parsed correctly from hello_world
	at org.apache.kafka.streams.processor.TaskId.parse(TaskId.java:120)
	at org.apache.kafka.streams.processor.internals.StateDirectory.parseTaskDirectoryName(StateDirectory.java:512)
	at org.apache.kafka.streams.processor.internals.StateDirectory.listNonEmptyTaskDirectories(StateDirectory.java:489)
	at org.apache.kafka.streams.processor.internals.TaskManager.tasksOnLocalStorage(TaskManager.java:1180)
	at org.apache.kafka.streams.processor.internals.StreamThread.runLoop(StreamThread.java:632)
	at org.apache.kafka.streams.processor.internals.StreamThread.run(StreamThread.java:575)

Diagnostic Commands

ls -la $STATE_DIR/<application.id>/   # task dirs must look like 0_0, 0_1, 1_3 (or <name>__0_0 for named topologies); anything else is corrupt

bin/kafka-streams-application-reset.sh --application-id <app-id> --bootstrap-server localhost:9092 --input-topics <topics>

rm -rf $STATE_DIR/<application.id>   # wipe local state after a reset so Streams recreates valid task directories

Hitting TaskIdFormatException 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 TaskIdFormatException

Common Causes

Solutions

Example Stack Trace

Diagnostic Commands

Related

Kafka Exception `TaskIdFormatException`