{"record":{"id":"83b89537b11beba1","repo":"apache/seatunnel","slug":"common-illegal-argument-commonerrorcodedeprecated-83b895","errorCode":"COMMON_ILLEGAL_ARGUMENT (CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT)","errorMessage":"avro_schema must be configured when strip_schema_registry_header is enabled for avro format","messagePattern":"avro_schema must be configured when strip_schema_registry_header is enabled for avro format","errorType":"error_code","errorClass":"SeaTunnelJsonFormatException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-kafka/src/main/java/org/apache/seatunnel/connectors/seatunnel/kafka/source/KafkaSourceConfig.java","lineNumber":430,"sourceCode":"                                Collections.singletonMap(\n                                        tablePath,\n                                        new DebeziumJsonDeserializationSchema(\n                                                catalogTable, true, includeSchema));\n                        schema =\n                                new DebeziumJsonDeserializationSchemaDispatcher(\n                                        tableDeserializationMap, true, includeSchema);\n                    } else {\n                        schema =\n                                new DebeziumJsonDeserializationSchema(\n                                        catalogTable, true, includeSchema);\n                    }\n                    break;\n                case AVRO:\n                    Optional<String> avroSchema = readonlyConfig.getOptional(AVRO_SCHEMA);\n                    boolean stripAvroSchemaRegistryHeader =\n                            readonlyConfig.get(STRIP_SCHEMA_REGISTRY_HEADER);\n                    if (stripAvroSchemaRegistryHeader && !avroSchema.isPresent()) {\n                        throw new SeaTunnelJsonFormatException(\n                                CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT,\n                                \"avro_schema must be configured when strip_schema_registry_header is enabled for avro format\");\n                    }\n                    schema =\n                            new AvroDeserializationSchema(\n                                    catalogTable,\n                                    avroSchema.orElse(null),\n                                    stripAvroSchemaRegistryHeader);\n                    break;\n                case PROTOBUF:\n                    boolean stripSchemaRegistryHeader =\n                            readonlyConfig.get(STRIP_SCHEMA_REGISTRY_HEADER);\n                    if (stripSchemaRegistryHeader) {\n                        schema = new SchemaRegistryAwareProtobufDeserializationSchema(catalogTable);\n                    } else {\n                        schema = new ProtobufDeserializationSchema(catalogTable);\n                    }\n                    break;","sourceCodeStart":412,"sourceCodeEnd":448,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-kafka/src/main/java/org/apache/seatunnel/connectors/seatunnel/kafka/source/KafkaSourceConfig.java#L412-L448","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add avro_schema = '<full Avro schema JSON>' to the Kafka source config.","Or set strip_schema_registry_header = false and use registry-aware deserialization.","Validate that the provided schema matches the topic's actual writer schema."],"exampleFix":"// before\nformat = avro\nstrip_schema_registry_header = true\n// after\nformat = avro\nstrip_schema_registry_header = true\navro_schema = \"{\\\"type\\\":\\\"record\\\",\\\"name\\\":\\\"Event\\\",\\\"fields\\\":[{\\\"name\\\":\\\"id\\\",\\\"type\\\":\\\"string\\\"}]}\"","handlingStrategy":"validation","validationCode":"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\"); }","typeGuard":null,"tryCatchPattern":"try { buildSource(cfg); } catch (SeaTunnelJsonFormatException e) { if (e.getMessage().contains(\"avro_schema\")) supplyAvroSchema(cfg); else throw e; }","preventionTips":["Pair strip_schema_registry_header=true with avro_schema every time.","Prefer registry-aware deserialization if no schema JSON is available."],"tags":["kafka","avro","config","schema"],"backgroundTag":"missing-required-config-field","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}