risingwavelabs/risingwave · error · ConnectorError

Unknown fields in the WITH clause

Error message

Unknown fields in the WITH clause: {:?}

What it means

try_from_btreemap converts a WITH-clause property map into the strongly-typed options struct P via serde. When deny_unknown_fields is set and the parsed struct reports keys that do not correspond to any declared option, the sink/source creation is aborted listing all unrecognized keys. This protects users from silently ignored typos in WITH options.

Solutions

1. Read the listed unknown fields and fix the option names in the WITH clause.
2. Consult the connector's documented options (`SHOW SOURCE connection` docs or risingwave docs) for valid keys.
3. Remove options that belong to a different connector type.
4. If an option should exist but doesn't, check for renames in the release notes of your RisingWave version.

Example fix

// before
WITH (connector='kafka', kafka.borker='localhost:9092')
// after
WITH (connector='kafka', kafka.broker='localhost:9092')

// validate WITH keys against the connector's documented options before running DDL
const KAFKA_OPTS: &[&str] = &["kafka.broker", "kafka.topic", "topic", "seed", ...];
fn unknown_opts(w: &BTreeMap<String, String>, known: &[&str]) -> Vec<&String> {
    w.keys().filter(|k| !known.contains(&k.as_str())).collect()
}

When it happens

Trigger: Executing CREATE SOURCE/CREATE SINK with WITH options that are not defined on the connector's properties struct — typos like connector='kafka', kafka.borker='x' — for connectors that deny unknown fields.

Common situations: Typos in option names; copying options from one connector to another that doesn't support them; using outdated option names after a RisingWave version renamed options.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• additional column type
• `checkpoint_read_chunk_size` must be greater than 0
• `checkpoint_read_max_in_flight_chunks` must be greater than…
• `commit_checkpoint_interval` must be greater than 0
• `commit_checkpoint_interval` must be greater than 0

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

Appendix: source

Thrown at src/connector/src/source/base.rs:144

}

pub trait UnknownFields {
    /// Unrecognized fields in the `WITH` clause.
    fn unknown_fields(&self) -> HashMap<String, String>;
}

impl<P: DeserializeOwned + UnknownFields> TryFromBTreeMap for P {
    fn try_from_btreemap(
        props: BTreeMap<String, String>,
        deny_unknown_fields: bool,
    ) -> Result<Self> {
        let json_value = serde_json::to_value(props)?;
        let res = serde_json::from_value::<P>(json_value)?;

        if !deny_unknown_fields || res.unknown_fields().is_empty() {
            Ok(res)
        } else {
            bail!(
                "Unknown fields in the WITH clause: {:?}",
                res.unknown_fields()
            )
        }
    }
}

#[derive(Default)]
pub struct CreateSplitReaderOpt {
    pub support_multiple_splits: bool,
    pub seek_to_latest: bool,
}

#[derive(Default)]
pub struct CreateSplitReaderResult {
    pub latest_splits: Option<Vec<SplitImpl>>,
    pub backfill_info: HashMap<SplitId, BackfillInfo>,
}

View on GitHub (pinned to 6469eb736d)