apache/seatunnel · error · SeaTunnelJsonFormatException

COMMON_ILLEGAL_ARGUMENT (CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT)

COMMON_ILLEGAL_ARGUMENT (CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT)

Error message

avro_schema must be configured when strip_schema_registry_header is enabled for avro format

What it means

When format=avro and strip_schema_registry_header=true, the connector needs the raw Avro writer schema to decode the payload after stripping the Confluent wire-format header. If avro_schema is not configured, createDeserializationSchema throws SeaTunnelJsonFormatException with ILLEGAL_ARGUMENT.

Solutions

1. Add avro_schema = '<full Avro schema JSON>' to the Kafka source config.
2. Or set strip_schema_registry_header = false and use registry-aware deserialization.
3. Validate that the provided schema matches the topic's actual writer schema.

Example fix

// before
format = avro
strip_schema_registry_header = true
// after
format = avro
strip_schema_registry_header = true
avro_schema = "{\"type\":\"record\",\"name\":\"Event\",\"fields\":[{\"name\":\"id\",\"type\":\"string\"}]}"

if (cfg.get("format").equals("avro") && cfg.get("strip_schema_registry_header") && !cfg.has("avro_schema")) { throw new IllegalArgumentException("avro_schema required when strip_schema_registry_header=true"); }

try { buildSource(cfg); } catch (SeaTunnelJsonFormatException e) { if (e.getMessage().contains("avro_schema")) supplyAvroSchema(cfg); else throw e; }

When it happens

Trigger: Kafka source config with format=avro, strip_schema_registry_header=true, and no avro_schema option defined; createDeserializationSchema (reached via schema()) detects the missing schema.

Common situations: Consuming Confluent Schema Registry Avro topics where the user strips the 5-byte header but forgets to supply the schema JSON; assuming the registry is auto-queried when this option bypasses it.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• COMMON_ILLEGAL_ARGUMENT (CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT)
• COMMON-02
• COMMON_ERROR_CODE-1
• COMMON_UNSUPPORTED_DATA_TYPE (CommonErrorCodeDeprecated.UNSUPPORTED_DATA_TYPE)
• COMMON_UNSUPPORTED_DATA_TYPE (CommonErrorCodeDeprecated.UNSUPPORTED_DATA_TYPE)

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/83b89537b11beba1. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-connectors-v2/connector-kafka/src/main/java/org/apache/seatunnel/connectors/seatunnel/kafka/source/KafkaSourceConfig.java:430

                                Collections.singletonMap(
                                        tablePath,
                                        new DebeziumJsonDeserializationSchema(
                                                catalogTable, true, includeSchema));
                        schema =
                                new DebeziumJsonDeserializationSchemaDispatcher(
                                        tableDeserializationMap, true, includeSchema);
                    } else {
                        schema =
                                new DebeziumJsonDeserializationSchema(
                                        catalogTable, true, includeSchema);
                    }
                    break;
                case AVRO:
                    Optional<String> avroSchema = readonlyConfig.getOptional(AVRO_SCHEMA);
                    boolean stripAvroSchemaRegistryHeader =
                            readonlyConfig.get(STRIP_SCHEMA_REGISTRY_HEADER);
                    if (stripAvroSchemaRegistryHeader && !avroSchema.isPresent()) {
                        throw new SeaTunnelJsonFormatException(
                                CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT,
                                "avro_schema must be configured when strip_schema_registry_header is enabled for avro format");
                    }
                    schema =
                            new AvroDeserializationSchema(
                                    catalogTable,
                                    avroSchema.orElse(null),
                                    stripAvroSchemaRegistryHeader);
                    break;
                case PROTOBUF:
                    boolean stripSchemaRegistryHeader =
                            readonlyConfig.get(STRIP_SCHEMA_REGISTRY_HEADER);
                    if (stripSchemaRegistryHeader) {
                        schema = new SchemaRegistryAwareProtobufDeserializationSchema(catalogTable);
                    } else {
                        schema = new ProtobufDeserializationSchema(catalogTable);
                    }
                    break;

View on GitHub (pinned to cf67b549a7)