risingwavelabs/risingwave · error · ConnectorError

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

Error emitted by generated validation code for `ALTER SOURCE ... ALTER on the fly`: the named field is not present in SOURCE_ALLOW_ALTER_ON_FLY_FIELDS for that connector, so altering it without a restart is rejected. This is a generic whitelist guard produced by the code generator; the input at fault is the field name passed to check_source_allow_alter_on_fly_fields.

Solutions

  1. Check the connector's registered allow_alter_on_fly fields and only alter supported fields.
  2. Fix field-name casing/typos to match the schema exactly.
  3. Plan the change as a full rebuild/refresh of the source instead of an on-the-fly alteration.
  4. If the field should be alterable, add it to the connector's allow list and regenerate.

Example fix

// before
check_source_allow_alter_on_fly_fields("kafka", &["message.key".into()])?;
// after
check_source_allow_alter_on_fly_fields("kafka", &["upsert_avro_primary_key".into()])?;
Defensive patterns

Strategy: validation

Validate before calling

fn can_alter(connector: &str, field: &str) -> bool {
    source_properties::source_name_to_prop_type_name(connector)
        .and_then(|t| SOURCE_ALLOW_ALTER_ON_FLY_FIELDS.get(t))
        .map(|f| f.iter().any(|x| x == field))
        .unwrap_or(false)
}

Try / catch

match check_source_allow_alter_on_fly_fields(connector, &fields) {
    Err(e) => return Err(sql_error::unsupported(&format!("alter rejected: {e}"))),
    Ok(()) => proceed_with_alter(),
}

Prevention

When it happens

Trigger: Calling check_source_allow_alter_on_fly_fields (e.g. during ALTER SOURCE / schema-change validation) with a field name that is not in SOURCE_ALLOW_ALTER_ON_FLY_FIELDS for that connector.

Common situations: Attempting to alter a non-mutable column (e.g. Kafka message key or header field) on the fly; typo in the field name; trying an alteration pattern the connector's schema evolution does not support.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at src/connector/src/with_options_test.rs:807

/// 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)