risingwavelabs/risingwave · error · SinkError::Config

Unknown fields in the WITH clause: {:?}

Error message

Unknown fields in the WITH clause: {:?}

What it means

`validate_sink_unknown_fields` checks sink WITH-clause properties against the known/supported keys for the chosen connector (removing recognized keys via `unknown_fields.remove(key)`); if any remain, they are listed in this Config error. It prevents silently ignoring misspelled or obsolete options.

Source

Thrown at src/connector/src/sink/mod.rs:337

    // even if a connector-specific config does not declare them.
    for key in [
        CONNECTOR_TYPE_KEY,
        SINK_TYPE_OPTION,
        SINK_SNAPSHOT_OPTION,
        SINK_USER_IGNORE_DELETE_OPTION,
        SINK_USER_FORCE_APPEND_ONLY_OPTION,
        SINK_USER_FORCE_COMPACTION,
        SINK_USER_PRESERVE_ROW_LEVEL_CHANGES,
        "backfill_rate_limit",
        "primary_key",
        "sink_rate_limit",
    ] {
        unknown_fields.remove(key);
    }
    if unknown_fields.is_empty() {
        Ok(())
    } else {
        Err(SinkError::Config(anyhow!(
            "Unknown fields in the WITH clause: {:?}",
            unknown_fields
        )))
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SinkParam {
    pub sink_id: SinkId,
    pub sink_name: String,
    pub properties: BTreeMap<String, String>,
    pub columns: Vec<ColumnDesc>,
    /// User-defined primary key indices for upsert sink, if any.
    pub downstream_pk: Option<Vec<usize>>,
    pub sink_type: SinkType,
    /// Whether to drop DELETE and convert UPDATE to INSERT in the sink executor.
    pub ignore_delete: bool,
    pub format_desc: Option<SinkFormatDesc>,

View on GitHub (pinned to 6469eb736d)

Solutions

1. Remove or correct the unknown WITH options listed in the error message
2. Check the connector's documentation for valid option names in this version
3. Update deprecated option names to their current equivalents

Example fix

// before
WITH (connector = 'kafka', primay_key = 'id')
// after
WITH (connector = 'kafka', primary_key = 'id')

let known: Vec<_> = spec_known_keys(connector);
let unknown: Vec<_> = props.keys().filter(|k| !known.contains(k)).collect();
if !unknown.is_empty() {
    return Err(anyhow!("Unknown fields in the WITH clause: {unknown:?}"));
}

if let Err(e) = validate_sink_unknown_fields(connector, &props) {
    // surface unknown keys to the user before retrying DDL
    return Err(anyhow!("fix WITH options: {e}"));
}

When it happens

Trigger: Calling `validate_sink_unknown_fields` with WITH properties containing keys not in the connector's known-field set — misspellings, deprecated options, or options belonging to a different connector.

Common situations: Typo'd WITH options like `primay_key`; copying sink options from another connector; options removed/renamed in a RisingWave upgrade.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• order_key must not be empty
• System column `{}` is not allowed in order_key
• Must specify 'connector' in WITH clause
• primary key not defined for {:?} pulsar sink (please define
• Redis Sink Primary Key must be specified.

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