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 connection: {connection_name}

What it means

Validation error from check_connection_allow_alter_on_fly_fields: while altering a connection's properties on the fly, the user requested changing field `field`, which is not in the per-connection-type whitelist (CONNECTION_ALLOW_ALTER_ON_FLY_FIELDS) for that connection. Only explicitly allow-listed fields may be altered without recreating the connection.

Source

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

    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}"
        )));
    };
    let Some(allowed_fields) = CONNECTION_ALLOW_ALTER_ON_FLY_FIELDS.get(type_name) else {
        return Err(ConnectorError::from(anyhow::anyhow!(
            "No allow_alter_on_fly fields registered for connection: {connection_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 connection: {connection_name}"
            )));
        }
    }
    Ok(())
}

/// Checks if all given fields are allowed to be altered on the fly for the specified sink connector.
/// Returns Ok(()) if all fields are allowed, otherwise returns a `ConnectorError`.
pub fn check_sink_allow_alter_on_fly_fields(
    sink_name: &str,
    fields: &[String],
) -> crate::error::ConnectorResult<()> {
    // TODO(#24846): JDBC sink currently uses `()` as sink config type in `for_all_sinks!`,
    // so it cannot have an isolated key in `SINK_ALLOW_ALTER_ON_FLY_FIELDS`.
    // Reuse the JDBC entry in `CONNECTION_ALLOW_ALTER_ON_FLY_FIELDS` for now.
    // TODO(#24846): remove this special case after JDBC sink has a dedicated config type
    // and allow-alter fields are generated directly into `SINK_ALLOW_ALTER_ON_FLY_FIELDS`.

View on GitHub (pinned to 6469eb736d)

Solutions

  1. Alter only allowlisted fields for the connection type
  2. Drop and recreate the connection with the new values
  3. Consult RW docs for the list of hot-alterable connection fields

Example fix

// before: ALTER CONNECTION c SET provider = 'aws'; -- not allowed
// after: DROP CONNECTION c; CREATE CONNECTION c WITH (provider='aws', ...);
Defensive patterns

Strategy: validation

Validate before calling

const CONNECTION_ALLOWED: &[&str] = &["endpoint","settings"]; // per-type allowlist
if !CONNECTION_ALLOWED.contains(&field) {
    return Err(format!("{field} is not hot-alterable"));
}

Try / catch

match res {
    Err(e) if e.to_string().contains("not allowed to be altered on the fly for connection") => {
        // fall back to DROP/CREATE CONNECTION
    }
    other => other?,
}

Prevention

When it happens

Trigger: ALTER CONNECTION attempting to change a field not present in CONNECTION_ALLOW_ALTER_ON_FLY_FIELDS for that connection type.

Common situations: Changing immutable connection properties (e.g. provider, service name) at runtime instead of only alterable ones like some endpoint/settings.

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/0bb61e1a52e23115. Report an issue: GitHub.