What causes SchemaProjectorException?

Schema NAME mismatch: SchemaProjector.checkMaybeCompatible requires source.name() == target.name(); when a sink projects an evolved record whose Connect schema name (record/namespace) changed (e.g. com.p1.p2.LogLine vs com.p1.LogLine), it throws 'Schema name mismatch'. Schema PARAMETERS not equal: even a harmless change like editing a field's doc/connect.record.doc parameter makes parameters differ and projection fails with 'Schema parameters not equal' (a known over-strict check). Missing schema VERSION for compatibility: storage sinks (HDFS/S3) doing BACKWARD/FORWARD checks need versioned schemas; using JsonConverter without Schema Registry (e.g. behind a Debezium source) yields unversioned schemas, throwing 'Schema version required for BACKWARD compatibility'. Incompatible type change between the stored/target schema and the incoming schema that isn't a valid promotion.

How do I fix SchemaProjectorException?

Keep the Connect schema name/namespace stable across versions; avoid source changes that rename the inferred schema. If names are auto-inferred, set explicit names in the converter to stop NAME_MISMATCH. Use a Schema Registry with Avro/Protobuf/JSON-Schema converters (not raw JsonConverter) so records carry a version, satisfying the sink's compatibility check; align Registry compatibility (BACKWARD/FORWARD) with how the sink projects. Make schema changes additive/compatible (add optional fields with defaults); avoid changing only doc/parameters expecting it to be a no-op, since Connect's projector compares parameters strictly. If you must move past an incompatible stored schema, roll the target to a new path (new HDFS/S3 partition/directory) so the sink starts a fresh schema lineage, or evolve the schema compatibly — rather than deleting registered Schema Registry versions, which breaks any consumer still reading them.

Is SchemaProjectorException retriable?

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

Kafka Exception `SchemaProjectorException`

org.apache.kafka.connect.errors.SchemaProjectorException

Non-retriable Connect

Indicates an error while projecting a schema via SchemaProjector

Common Causes

Schema NAME mismatch: SchemaProjector.checkMaybeCompatible requires source.name() == target.name(); when a sink projects an evolved record whose Connect schema name (record/namespace) changed (e.g. com.p1.p2.LogLine vs com.p1.LogLine), it throws 'Schema name mismatch'.
Schema PARAMETERS not equal: even a harmless change like editing a field's doc/connect.record.doc parameter makes parameters differ and projection fails with 'Schema parameters not equal' (a known over-strict check).
Missing schema VERSION for compatibility: storage sinks (HDFS/S3) doing BACKWARD/FORWARD checks need versioned schemas; using JsonConverter without Schema Registry (e.g. behind a Debezium source) yields unversioned schemas, throwing 'Schema version required for BACKWARD compatibility'.
Incompatible type change between the stored/target schema and the incoming schema that isn't a valid promotion.

Solutions

Keep the Connect schema name/namespace stable across versions; avoid source changes that rename the inferred schema. If names are auto-inferred, set explicit names in the converter to stop NAME_MISMATCH.
Use a Schema Registry with Avro/Protobuf/JSON-Schema converters (not raw JsonConverter) so records carry a version, satisfying the sink's compatibility check; align Registry compatibility (BACKWARD/FORWARD) with how the sink projects.
Make schema changes additive/compatible (add optional fields with defaults); avoid changing only doc/parameters expecting it to be a no-op, since Connect's projector compares parameters strictly.
If you must move past an incompatible stored schema, roll the target to a new path (new HDFS/S3 partition/directory) so the sink starts a fresh schema lineage, or evolve the schema compatibly — rather than deleting registered Schema Registry versions, which breaks any consumer still reading them.

Example Stack Trace

org.apache.kafka.connect.errors.SchemaProjectorException: Schema name mismatch. source name: com.example.OrderV2 and target name: com.example.OrderV1
	at org.apache.kafka.connect.data.SchemaProjector.checkMaybeCompatible(SchemaProjector.java:103)
	at org.apache.kafka.connect.data.SchemaProjector.project(SchemaProjector.java:70)
	at io.confluent.connect.storage.schema.StorageSchemaCompatibility.project(StorageSchemaCompatibility.java:179)
	at io.confluent.connect.hdfs.TopicPartitionWriter.write(TopicPartitionWriter.java:420)
	at org.apache.kafka.connect.runtime.WorkerSinkTask.deliverMessages(WorkerSinkTask.java:585)

Diagnostic Commands

curl -s http://localhost:8083/connectors/<sink>/status | jq '.tasks[].trace'   # see whether it's name mismatch / parameters / version-required

curl -s http://localhost:8081/subjects/<topic>-value/versions | jq .   # list registered schema versions for the topic

curl -s http://localhost:8081/config/<topic>-value | jq .   # check the per-subject compatibility level

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

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

Common Causes

Solutions

Example Stack Trace

Diagnostic Commands

Related

Kafka Exception `SchemaProjectorException`