risingwavelabs/risingwave · error · anyhow::Error

missing system param {:?}

Error message

missing system param {:?}

What it means

This error comes from `check_missing_params`, invoked inside `system_params_to_model`, which derives the persisted system-parameter rows from a `PbSystemParams` protobuf. Every system parameter field must be `Some` before serialization; if any field is `None` the macro-generated code aborts with "missing system param {:?}". It is an internal invariant: the meta service refuses to persist a partial set of system parameters to the database.

Source

Thrown at src/meta/src/controller/system_param.rs:86

                }
            });
            derive_missing_fields(&mut params);
            if !models.is_empty() {
                let unrecognized_params = models.into_iter().map(|model| model.name).collect::<Vec<_>>();
                tracing::warn!("unrecognized system params {:?}", unrecognized_params);
            }
            Ok(params)
        }
    };
}

/// Derive serialization to db models.
macro_rules! impl_system_params_to_models {
    ($({ $field:ident, $type:ty, $default:expr, $is_mutable:expr, $($rest:tt)* },)*) => {
        #[expect(deprecated)]
        #[allow(clippy::vec_init_then_push)]
        pub fn system_params_to_model(params: &PbSystemParams) -> MetaResult<Vec<system_parameter::ActiveModel>> {
            check_missing_params(params).map_err(|e| anyhow!(e))?;
            let mut models = Vec::new();
            $(
                let value = params.$field.as_ref().unwrap().to_string();
                models.push(system_parameter::ActiveModel {
                    name: Set(key_of!($field).to_string()),
                    value: Set(value),
                    is_mutable: Set($is_mutable),
                    description: Set(None),
                });
            )*
            Ok(models)
       }
    };
}

// For each field in `persisted` and `init`
// 1. Some, None: The persisted field is deprecated, so just ignore it.
// 2. Some, Some: Check equality and warn if they differ.

View on GitHub (pinned to 6469eb736d)

Solutions

1. Ensure every optional field of `PbSystemParams` is populated before serialization — start from the documented defaults (`SystemParams::default()` / example config) and merge, rather than constructing a bare proto.
2. Merge persisted DB params over a complete default set (see `merge_params` usage in `SystemController::new`) so missing fields are backfilled with defaults.
3. If this happens after a version upgrade, run the upgrade path that seeds newly introduced parameters instead of loading the raw DB rows directly.
4. Check `check_missing_params` output — it names the missing field — and set that parameter explicitly (ALTER SYSTEM / bootstrap config).

Example fix

// before
let params: PbSystemParams = read_from_db_only();
system_params_to_model(&params)?;
// after
let params = merge_params(system_params_from_db(db_params)?, PbSystemParams::default());
system_params_to_model(&params)?;

fn ensure_params_complete(p: &PbSystemParams) -> Result<(), String> {
    let missing: Vec<&str> = [
        ("backup_config", p.backup_config.is_none()),
        ("barrier_interval", p.barrier_interval.is_none()),
    ].iter().filter(|(_, m)| *m).map(|(n, _)| *n).collect();
    if missing.is_empty() { Ok(()) } else { Err(format!("missing: {:?}", missing)) }
}

When it happens

Trigger: Calling `system_params_to_model` with a `PbSystemParams` whose optional proto fields are unset (e.g. params loaded from an older cluster version, or a manually constructed `PbSystemParams` missing fields).

Common situations: Rolling upgrades where new parameters were introduced and stored snapshots lack them without a migration; tools or tests that build `PbSystemParams` by hand and forget to fill in all fields; a corrupted/edited system_parameter table combined with incomplete defaults.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• batch refresh job {} has no snapshot backfill info
• recovered snapshot backfill job {} has no snapshot backfill
• catalog object {} has no database
• job fragments should exist for streaming job
• streaming job should exist for loaded context

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