risingwavelabs/risingwave · error · ConnectorError

Field '{field}' is not allowed to be altered on the fly for

Error message

Field '{field}' is not allowed to be altered on the fly for connector: {connector_name}

What it means

The field being altered is not in the connector's allow_alter_on_fly allowlist, so it cannot be changed on the fly for that source. Only fields explicitly registered as mutable-on-the-fly are permitted.

Source

Thrown at src/connector/src/allow_alter_on_fly_fields.rs:479

/// Returns Ok(()) if all fields are allowed, otherwise returns a `ConnectorError`.
pub fn check_source_allow_alter_on_fly_fields(
    connector_name: &str,
    fields: &[String],
) -> crate::error::ConnectorResult<()> {
    // Convert connector name to the type name key
    let Some(type_name) = source_properties::source_name_to_prop_type_name(connector_name) else {
        return Err(ConnectorError::from(anyhow::anyhow!(
            "Unknown source connector: {connector_name}"
        )));
    };
    let Some(allowed_fields) = SOURCE_ALLOW_ALTER_ON_FLY_FIELDS.get(type_name) else {
    return Err(ConnectorError::from(anyhow::anyhow!(
        "No allow_alter_on_fly fields registered for connector: {connector_name}"
    )));
    };
    for field in fields {
        if !allowed_fields.contains(field) {
            return Err(ConnectorError::from(anyhow::anyhow!(
                "Field '{field}' is not allowed to be altered on the fly for connector: {connector_name}"
            )));
        }
    }
    Ok(())
}

pub fn check_connection_allow_alter_on_fly_fields(
    connection_name: &str,
    fields: &[String],
) -> crate::error::ConnectorResult<()> {
    use crate::source::connection_name_to_prop_type_name;

    // Convert connection name to the type name key
    let Some(type_name) = connection_name_to_prop_type_name(connection_name) else {
        return Err(ConnectorError::from(anyhow::anyhow!(
            "Unknown connection: {connection_name}"
        )));

View on GitHub (pinned to 6469eb736d)

Solutions

  1. Check documentation for which fields are allow-alter-on-fly for this connector and alter only those
  2. Recreate the source (drop + create) with the new field values
  3. Upgrade RW if the field became hot-alterable in a newer version

Example fix

// before: ALTER SOURCE s SET topic = 'other-topic'; -- not allowed
// after: recreate the source with the new topic
Defensive patterns

Strategy: validation

Validate before calling

const ALLOWED: &[&str] = &["topic","region"]; // per-connector allowlist
fn ensure_field_allowed(connector: &str, field: &str) -> Result<(), String> {
    if ALLOWED.contains(&field) { Ok(()) } else { Err(format!("{field} not hot-alterable for {connector}")) }
}

Try / catch

match res {
    Err(e) if e.to_string().contains("not allowed to be altered on the fly") => {
        // switch to recreate-the-source path
    }
    other => other?,
}

Prevention

When it happens

Trigger: ALTER SOURCE trying to modify/add a field (e.g. a WITH property like 'topic' vs a disallowed one) that is not in SOURCE_ALLOW_ALTER_ON_FLY_FIELDS for the connector.

Common situations: Trying to change core connector options (e.g. bootstrap.servers, topic) at runtime; assuming all properties are hot-alterable.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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