risingwavelabs/risingwave · error

unused FORMAT ENCODE option: key.message='{name}'

Error message

unused FORMAT ENCODE option: key.message='{name}'

What it means

When creating an Avro parser from a schema_location (schema registry URL), the optional key_record_name option (key.message) has no meaning — the key schema is derived by subject-name strategy, not by a record name. The parser rejects the combination instead of silently ignoring it.

Source

Thrown at src/connector/src/parser/avro/parser.rs:190

        let AvroProperties {
            schema_location,
            record_name,
            key_record_name,
            map_handling,
        } = try_match_expand!(encoding_properties, EncodingProperties::Avro)?;
        match schema_location {
            SchemaLocation::Confluent {
                urls: schema_location,
                client_config,
                name_strategy,
                topic,
            } => {
                let url = handle_sr_list(schema_location.as_str())?;
                let client = Client::new(url, &client_config)?;
                let resolver = ConfluentSchemaCache::new(client);

                if let Some(name) = &key_record_name {
                    bail!("unused FORMAT ENCODE option: key.message='{name}'");
                }
                let subject_value = get_subject_by_strategy(
                    &name_strategy,
                    topic.as_str(),
                    record_name.as_deref(),
                    false,
                )?;
                tracing::debug!("value subject {subject_value}");

                Ok(Self {
                    schema: Arc::new(ResolvedAvroSchema::create(
                        resolver.get_by_subject(&subject_value).await?,
                    )?),
                    writer_schema_cache: WriterSchemaCache::Confluent(Arc::new(resolver)),
                    map_handling,
                })
            }
            SchemaLocation::File {

View on GitHub (pinned to 6469eb736d)

Solutions

1. Remove the `key.message` option from the source definition
2. If a specific key record name is required, switch to the upsert Avro path (row_schema_location / confluent-wire-schema) where key.record.name is honored
3. Verify with SHOW SOURCE / CREATE SOURCE DDL that key.message is not present

Example fix

-- before
CREATE SOURCE s (...) WITH (...) FORMAT PLAIN ENCODE AVRO (schema.location='http://sr:8081', key.message='MyKey');
-- after
CREATE SOURCE s (...) WITH (...) FORMAT PLAIN ENCODE AVRO (schema.location='http://sr:8081');

const unused = ["key.message"].filter(k => Object.keys(avroOptions).includes(k));
if (schemaLocation && unused.length) throw new Error(`Remove option(s) ${unused} for schema.location-based Avro sources`);

catch (e) { if (/unused FORMAT ENCODE option/.test(e.message)) { strip key.message and retry } else throw e; }

When it happens

Trigger: Calling ParserConfig::new with SourceFormat::Plain + SourceEncode::Avro and schema_location set, while also passing the `key.message` option.

Common situations: Copy-pasting DEBEZIUM/protobuf-style config (where key.message is valid) into a plain Avro source; applying a template config from an upsert-avro source.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• payload shorter than 18-byte glue header
• Only support glue header version 3 but found {}
• protobuf file location not provided
• Unsupported format {:?} encode {:?}
• Must specify '{}' or '{}'

AI-assisted analysis of risingwavelabs/risingwave@6469eb736d (2026-09-11). Data as JSON: /api/errors/ee8d1c9e9e8e6d7f. Report an issue: GitHub.