Kafka Exception ConnectException
org.apache.kafka.connect.errors.ConnectException
Non-retriable
Connect
ConnectException is the top-level exception type generated by Kafka Connect and connector implementations.
Common Causes
- A sink/source task can't reach its external system (wrong host/URL, DNS, auth, SSL, timeout) — e.g. a sink configured with `127.0.0.1` inside a container that can't route to the real target; the connector wraps the underlying IOException in ConnectException and the task dies.
- An unrecoverable data/serialization problem propagates up: a converter or SMT throws, the WorkerSinkTask exits with 'Exiting WorkerSinkTask due to unrecoverable exception' wrapping the real cause.
- Connector implementation bugs: required config missing, a `start()`/`put()` path throws a runtime exception, or the connector explicitly throws ConnectException for a fatal condition.
- Target-system rejection: the external store returns a hard error (403 forbidden, mapping/parse error, constraint violation) that the connector treats as non-retriable.
Solutions
- Always read the `Caused by:` chain, not the top ConnectException line — the root cause (java.net.ConnectException, 403, parse error) is nested below it.
- For connectivity: fix the endpoint to a routable address (service DNS name, not 127.0.0.1 in Docker/K8s), verify credentials/TLS, and set sensible timeouts.
- For poison records, enable error tolerance + DLQ so one bad record doesn't kill the task: `errors.tolerance=all`, `errors.deadletterqueue.topic.name=<dlq>`, `errors.deadletterqueue.context.headers.enable=true`.
- Restart just the failed task once the cause is fixed: `curl -X POST http://connect:8083/connectors/<name>/tasks/<id>/restart` (restarting the connector is separate from restarting a task).
Example Stack Trace
ERROR WorkerSinkTask{id=influxdb-sink-0} Task threw an uncaught and unrecoverable exception. Task is being killed and will not recover until manually restarted (org.apache.kafka.connect.runtime.WorkerTask)
org.apache.kafka.connect.errors.ConnectException: Exiting WorkerSinkTask due to unrecoverable exception.
at org.apache.kafka.connect.runtime.WorkerSinkTask.deliverMessages(WorkerSinkTask.java:586)
at org.apache.kafka.connect.runtime.WorkerSinkTask.poll(WorkerSinkTask.java:323)
at org.apache.kafka.connect.runtime.WorkerSinkTask.iteration(WorkerSinkTask.java:226)
at org.apache.kafka.connect.runtime.WorkerSinkTask.execute(WorkerSinkTask.java:204)
at org.apache.kafka.connect.runtime.WorkerTask.doRun(WorkerTask.java:188)
Caused by: java.net.ConnectException: Failed to connect to /127.0.0.1:8086Diagnostic Commands
curl -s http://localhost:8083/connectors/<name>/status | jq '.tasks[] | {id, state, trace}' # see the FAILED task's stack trace
curl -X POST http://localhost:8083/connectors/<name>/tasks/0/restart # restart a single failed task
curl -X POST http://localhost:8083/connectors/<name>/restart?includeTasks=true # restart connector + its tasksRelated
Related Connect exceptions: AlreadyExistsException · DataException · IllegalWorkerStateException · NotFoundException · SchemaBuilderException · SchemaProjectorException
Hitting
ConnectException in production? Conduktor Console gives you real-time visibility into clients, consumer groups, and broker health. Browse every Kafka exception or protocol error code.