What causes IllegalWorkerStateException?

A custom `SinkTask` calls `context.assignment()` before the task is initialized (e.g. inside `start()` or the constructor), while the underlying consumer is still null. `context.pause(...)` or `context.resume(...)` is invoked too early in the lifecycle (before partitions are opened), tripping the same initialization guard. Connector code accesses task context from a background thread that runs before the framework finishes `initialize()`/`open()`. Lifecycle methods are called out of order in a hand-rolled connector, so assignment-dependent logic executes before Connect has wired the consumer in.

How do I fix IllegalWorkerStateException?

Never call `context.assignment()`, `pause()`, or `resume()` from `start()` — move assignment-dependent logic into `open(Collection )`, which the framework calls once partitions are assigned. Do per-record work and any consumer interaction from `put(Collection )`, where the consumer is guaranteed initialized. If you manage offsets externally, reset them via `context.offset(Map)` inside `open()`/on rebalance, not in the constructor or `start()`. Guard background threads so they don't touch the context until `open()` has fired at least once.

Is IllegalWorkerStateException retriable?

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

Kafka Exception `IllegalWorkerStateException`

org.apache.kafka.connect.errors.IllegalWorkerStateException

Non-retriable Connect

Indicates that a method has been invoked illegally or at an invalid time by a connector or task.

Common Causes

A custom `SinkTask` calls `context.assignment()` before the task is initialized (e.g. inside `start()` or the constructor), while the underlying consumer is still null.
`context.pause(...)` or `context.resume(...)` is invoked too early in the lifecycle (before partitions are opened), tripping the same initialization guard.
Connector code accesses task context from a background thread that runs before the framework finishes `initialize()`/`open()`.
Lifecycle methods are called out of order in a hand-rolled connector, so assignment-dependent logic executes before Connect has wired the consumer in.

Solutions

Never call `context.assignment()`, `pause()`, or `resume()` from `start()` — move assignment-dependent logic into `open(Collection<TopicPartition>)`, which the framework calls once partitions are assigned.
Do per-record work and any consumer interaction from `put(Collection<SinkRecord>)`, where the consumer is guaranteed initialized.
If you manage offsets externally, reset them via `context.offset(Map)` inside `open()`/on rebalance, not in the constructor or `start()`.
Guard background threads so they don't touch the context until `open()` has fired at least once.

Example Stack Trace

org.apache.kafka.connect.errors.IllegalWorkerStateException: SinkTaskContext may not be used to look up partition assignment until the task is initialized
	at org.apache.kafka.connect.runtime.WorkerSinkTaskContext.assignment(WorkerSinkTaskContext.java:126)
	at com.example.connect.MySinkTask.start(MySinkTask.java:58)
	at org.apache.kafka.connect.runtime.WorkerSinkTask.initializeAndStart(WorkerSinkTask.java:309)
	at org.apache.kafka.connect.runtime.WorkerTask.doRun(WorkerTask.java:185)
	at org.apache.kafka.connect.runtime.WorkerTask.run(WorkerTask.java:240)

Diagnostic Commands

curl -s http://localhost:8083/connectors/<name>/status | jq '.tasks[] | {id, state, trace}'   # FAILED task trace points at the offending context call

Related Connect exceptions: AlreadyExistsException · ConnectException · DataException · NotFoundException · SchemaBuilderException · SchemaProjectorException

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

Common Causes

Solutions

Example Stack Trace

Diagnostic Commands

Related

Kafka Exception `IllegalWorkerStateException`