What causes "Unknown connection: {connection_name}" in risingwavelabs/risingwave?

Use a registered connection type name (e.g. as defined by the connection registry in src/connector/src/source).

risingwavelabs/risingwave · error · ConnectorError

Unknown connection

Error message

Unknown connection: {connection_name}

What it means

Raised by check_connection_allow_alter_on_fly_fields when connection_name cannot be mapped to a known connection type via connection_name_to_prop_type_name, so the connection's alterable-field registry cannot be looked up.

Solutions

Use a registered connection type name (e.g. as defined by the connection registry in src/connector/src/source).
Fix typos and casing of the connection name.
If introducing a new connection type, register it in connection_name_to_prop_type_name and its allow fields, then regenerate.

Example fix

// before
check_connection_allow_alter_on_fly_fields("privatelink-aws", &fields)?;
// after
check_connection_allow_alter_on_fly_fields("privatelink", &fields)?;

Defensive patterns

Strategy: validation

Validate before calling

fn is_known_connection(name: &str) -> bool {
    risingwave_connector::source::connection_name_to_prop_type_name(name).is_some()
}

Try / catch

match check_connection_allow_alter_on_fly_fields(conn_name, &fields) {
    Ok(()) => {},
    Err(e) => eprintln!("unknown connection '{}': {}", conn_name, e),
}

Prevention

Use connection type names from CREATE CONNECTION docs, not instance names
Validate connection names with the registry before schema-change planning

When it happens

Trigger: Passing an unknown connection name (from CREATE CONNECTION / USING CONNECTION) to the allow-alter-on-fly validation, e.g. a typo or a connection type not registered in the codebase.

Common situations: Typo in a private-link/ES connection name; referencing a connection type added in a newer version; mixing connection names with connector names by mistake.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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

Appendix: source

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

    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}}"
        )));
    }};
    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(())
}}

View on GitHub (pinned to 6469eb736d)