What causes AlreadyExistsException?

POST /connectors is called with a connector `name` that already exists in the cluster; the Connect REST layer rejects the duplicate and the herder surfaces AlreadyExistsException (HTTP 409 Conflict). Two automation paths (e.g. a CI deploy job and a GitOps operator, or two replicas of the same bootstrap script) race to create the same connector concurrently; the second writer loses and gets AlreadyExistsException. A connector was deleted and immediately re-created before the delete propagated through the config topic / group rebalance, so the herder still sees the old name as present. Custom herder/connector code calls a create-style API (createConnector / putConnectorConfig with allowReplace=false) for an entity that the framework already tracks.

How do I fix AlreadyExistsException?

Use idempotent upsert instead of create: `PUT /connectors/{name}/config` creates-or-updates and never throws on an existing name, unlike `POST /connectors`. Make deploy scripts check existence first: `curl -s -o /dev/null -w '%{http_code}' http://connect:8083/connectors/ ` and branch on 404 (create) vs 200 (update). Pick a unique connector name per environment/version (e.g. suffix with env or a hash) so re-deploys don't collide; treat connector name as a primary key. If you intend to replace it, delete first (`DELETE /connectors/{name}`), poll until `GET` returns 404, then create — or just switch to the PUT-config endpoint to avoid the dance entirely.

Is AlreadyExistsException retriable?

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

Kafka Exception `AlreadyExistsException`

org.apache.kafka.connect.errors.AlreadyExistsException

Non-retriable Connect

Indicates the operation tried to create an entity that already exists.

Common Causes

POST /connectors is called with a connector `name` that already exists in the cluster; the Connect REST layer rejects the duplicate and the herder surfaces AlreadyExistsException (HTTP 409 Conflict).
Two automation paths (e.g. a CI deploy job and a GitOps operator, or two replicas of the same bootstrap script) race to create the same connector concurrently; the second writer loses and gets AlreadyExistsException.
A connector was deleted and immediately re-created before the delete propagated through the config topic / group rebalance, so the herder still sees the old name as present.
Custom herder/connector code calls a create-style API (createConnector / putConnectorConfig with allowReplace=false) for an entity that the framework already tracks.

Solutions

Use idempotent upsert instead of create: `PUT /connectors/{name}/config` creates-or-updates and never throws on an existing name, unlike `POST /connectors`.
Make deploy scripts check existence first: `curl -s -o /dev/null -w '%{http_code}' http://connect:8083/connectors/<name>` and branch on 404 (create) vs 200 (update).
Pick a unique connector name per environment/version (e.g. suffix with env or a hash) so re-deploys don't collide; treat connector name as a primary key.
If you intend to replace it, delete first (`DELETE /connectors/{name}`), poll until `GET` returns 404, then create — or just switch to the PUT-config endpoint to avoid the dance entirely.

Example Stack Trace

org.apache.kafka.connect.errors.AlreadyExistsException: Connector my-jdbc-source already exists
	at org.apache.kafka.connect.runtime.distributed.DistributedHerder.lambda$putConnectorConfig$8(DistributedHerder.java:1023)
	at org.apache.kafka.connect.runtime.distributed.DistributedHerder.tick(DistributedHerder.java:475)
	at org.apache.kafka.connect.runtime.distributed.DistributedHerder.run(DistributedHerder.java:380)
	at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:539)
	at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)

Diagnostic Commands

curl -s http://localhost:8083/connectors | jq .   # list existing connector names before creating

curl -i -X PUT -H 'Content-Type: application/json' --data @config.json http://localhost:8083/connectors/my-jdbc-source/config   # idempotent create-or-update

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8083/connectors/my-jdbc-source   # 200=exists, 404=safe to POST

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

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

Common Causes

Solutions

Example Stack Trace

Diagnostic Commands

Related

Kafka Exception `AlreadyExistsException`