What causes SchemaBuilderException?

Adding two fields with the same name to one struct: SchemaBuilder.struct().field("x", ...).field("x", ...) throws 'Cannot create field because of field name duplication x'. Common when a custom connector/SMT builds a schema from a source whose columns collide (case-folding, flattening nested fields, duplicate CSV headers). Debezium ByLogicalTableRouter applied twice (chained reroute SMTs) re-inserts the key field __dbz__physicalTableIdentifier into a key schema that already has it, throwing the duplication error. Setting an immutable SchemaBuilder property twice with conflicting values: calling .name()/.version()/.doc()/.optional()/.required()/.defaultValue() more than once throws 'Invalid SchemaBuilder call: has already been set'. Calling .field(...) on a non-struct builder (e.g. on a primitive or array type) throws 'Cannot create fields on type '.

How do I fix SchemaBuilderException?

Ensure field names are unique within each struct — de-duplicate or rename colliding source columns (e.g. via a RenameField/ReplaceField SMT) before building the schema. For Debezium routing, don't chain two ByLogicalTableRouter transforms: drop the schema name from topic naming and apply a single router; or set transforms. .key.field.name to a unique name that won't collide with existing key fields. (Gunnar Morling's guidance on the duplication case.) Build each SchemaBuilder once: set name/version/doc/optional exactly one time per builder instance; cache and reuse the built Schema rather than re-running setters. Call .field() only on SchemaBuilder.struct(); use .build() at the end and don't mutate a builder after building.

Is SchemaBuilderException retriable?

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

Kafka Exception `SchemaBuilderException`

org.apache.kafka.connect.errors.SchemaBuilderException

Non-retriable Connect

Indicates an error while building a schema via SchemaBuilder

Common Causes

Adding two fields with the same name to one struct: SchemaBuilder.struct().field("x", ...).field("x", ...) throws 'Cannot create field because of field name duplication x'. Common when a custom connector/SMT builds a schema from a source whose columns collide (case-folding, flattening nested fields, duplicate CSV headers).
Debezium ByLogicalTableRouter applied twice (chained reroute SMTs) re-inserts the key field __dbz__physicalTableIdentifier into a key schema that already has it, throwing the duplication error.
Setting an immutable SchemaBuilder property twice with conflicting values: calling .name()/.version()/.doc()/.optional()/.required()/.defaultValue() more than once throws 'Invalid SchemaBuilder call: <prop> has already been set'.
Calling .field(...) on a non-struct builder (e.g. on a primitive or array type) throws 'Cannot create fields on type <T>'.

Solutions

Ensure field names are unique within each struct — de-duplicate or rename colliding source columns (e.g. via a RenameField/ReplaceField SMT) before building the schema.
For Debezium routing, don't chain two ByLogicalTableRouter transforms: drop the schema name from topic naming and apply a single router; or set transforms.<r>.key.field.name to a unique name that won't collide with existing key fields. (Gunnar Morling's guidance on the duplication case.)
Build each SchemaBuilder once: set name/version/doc/optional exactly one time per builder instance; cache and reuse the built Schema rather than re-running setters.
Call .field() only on SchemaBuilder.struct(); use .build() at the end and don't mutate a builder after building.

Example Stack Trace

org.apache.kafka.connect.errors.SchemaBuilderException: Cannot create field because of field name duplication __dbz__physicalTableIdentifier
	at org.apache.kafka.connect.data.SchemaBuilder.field(SchemaBuilder.java:347)
	at io.debezium.transforms.ByLogicalTableRouter.updateKeySchema(ByLogicalTableRouter.java:289)
	at io.debezium.transforms.ByLogicalTableRouter.apply(ByLogicalTableRouter.java:212)
	at org.apache.kafka.connect.runtime.TransformationChain.apply(TransformationChain.java:50)
	at org.apache.kafka.connect.runtime.WorkerSourceTask.convertTransformedRecord(WorkerSourceTask.java:290)

Diagnostic Commands

curl -s http://localhost:8083/connectors/<name>/config | jq '.config | with_entries(select(.key|startswith("transforms")))'   # inspect the SMT chain for duplicate/chained routers

curl -s http://localhost:8083/connectors/<name>/status | jq '.tasks[].trace'   # read the full stack trace incl. the duplicated field name

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

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

Common Causes

Solutions

Example Stack Trace

Diagnostic Commands

Related

Kafka Exception `SchemaBuilderException`