risingwavelabs/risingwave · error · SessionConfigError

unrecognized configs: {:?}

Error message

unrecognized configs: {:?}

What it means

This error is raised when a user-provided streaming config override (e.g. via SET in a session, applied through merge_streaming_config_section) contains keys that do not exist in StreamingConfig. The merge succeeds but the merged config reports unrecognized_keys, and the session config layer deliberately fails fast rather than silently ignoring typos. It exists to catch config key misspellings and removed/renamed settings before they cause confusing runtime behavior.

Source

Thrown at src/common/src/session_config/mod.rs:712

                .upsert("streaming.developer.over_window_cache_policy", v)
                .unwrap();
        }
        if let Some(v) = self.streaming_cache_refill_policy.as_ref() {
            table
                .upsert("streaming.developer.cache_refill_policy", v)
                .unwrap();
        }

        let res = toml::to_string(&table)?;

        // Validate all fields are valid by trying to merge it to the default config.
        if !res.is_empty() {
            let merged =
                merge_streaming_config_section(&StreamingConfig::default(), res.as_str())?.unwrap();

            let unrecognized_keys = merged.unrecognized_keys().collect_vec();
            if !unrecognized_keys.is_empty() {
                bail!("unrecognized configs: {:?}", unrecognized_keys);
            }
        }

        Ok(res)
    }
}

#[cfg(test)]
mod test {
    use expect_test::expect;

    use super::*;

    #[derive(SessionConfig)]
    struct TestConfig {
        #[parameter(default = 1, flags = "NO_ALTER_SYS", alias = "test_param_alias" | "alias_param_test")]
        test_param: i32,
        #[parameter(default = false, deprecated = "deprecated test notice")]

View on GitHub (pinned to 6469eb736d)

Solutions

1. Check the reported unrecognized key names and correct the spelling to match a valid StreamingConfig field.
2. Consult src/common/src/config/src/streaming_config.rs (or the generated docs) for the exact valid key names.
3. If the key was renamed in a newer version, migrate to the new key name.
4. If the setting genuinely doesn't exist, remove it from the SET statement.

Example fix

// before
SET streaming_config = 'chunk_szie = 512';
// after
SET streaming_config = 'chunk_size = 512';

// Before SET streaming_config, verify keys against StreamingConfig fields
let valid_keys: Vec<&str> = StreamingConfig::default().recognized_keys().collect();
for key in user_keys {
    assert!(valid_keys.contains(&key.as_str()), "unknown streaming config key: {}", key);
}

match session.set_config(key, value) {
    Err(e) if e.to_string().starts_with("unrecognized configs") => {
        log::warn!("typo in streaming config: {e}");
        // surface the unrecognized key list to the user
    }
    other => other?,
}

When it happens

Trigger: Calling SET streaming_config (or the session config set path that ends at this code in src/common/src/session_config/mod.rs:712) with a config string containing a key not present in StreamingConfig's TOML schema, e.g. 'SET streaming_config = 'wrong_key = 1';' or using a key that was renamed in a newer RisingWave version.

Common situations: Typo in a config key; copying config from an older RisingWave version where the key was renamed or removed; copying a batch/frontend config key into the streaming section; mixing table names into config.

Related errors

• Invalid value for Bounded strategy: must be positive integer
• config error: {0}
• Unsupported parallelism: {0}
• Unsupported strategy: {0}
• Invalid value for Ratio strategy: must be between 0.0 and 1.

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