to use iceberg engine table, the variable `iceberg_engine_co

Error message

to use iceberg engine table, the variable `iceberg_engine_connection` must be set.

What it means

RisingWave requires an Iceberg catalog connection to create an Iceberg engine table. The session variable `iceberg_engine_connection` identifies that connection as `<database>.<connection_name>`. If the variable is empty, `create_iceberg_engine_table` bails because it cannot resolve a catalog for the table.

Source

Thrown at src/frontend/src/handler/create_table.rs:1913

        .read_guard()
        .get_schema_by_id(table.database_id, table.schema_id)?
        .name()
        .clone();
    let iceberg_catalog_name = rw_db_name.clone();
    let iceberg_database_name = rw_schema_name.clone();
    let iceberg_table_name = table_name.0.last().unwrap().real_value();

    let iceberg_engine_connection: String = session.config().iceberg_engine_connection();
    let sink_decouple = session.config().sink_decouple();
    if matches!(sink_decouple, SinkDecouple::Disable) {
        bail!(
            "Iceberg engine table only supports with sink decouple, try `set sink_decouple = true` to resolve it"
        );
    }

    let mut connection_ref = BTreeMap::new();
    let with_common = if iceberg_engine_connection.is_empty() {
        bail!("to use iceberg engine table, the variable `iceberg_engine_connection` must be set.");
    } else {
        let parts: Vec<&str> = iceberg_engine_connection.split('.').collect();
        assert_eq!(parts.len(), 2);
        let connection_catalog =
            session.get_connection_by_name(Some(parts[0].to_owned()), parts[1])?;
        if let ConnectionInfo::ConnectionParams(params) = &connection_catalog.info {
            if params.connection_type == ConnectionType::Iceberg as i32 {
                // With iceberg engine connection:
                connection_ref.insert(
                    "connection".to_owned(),
                    ConnectionRefValue {
                        connection_name: ObjectName::from(vec![
                            Ident::from(parts[0]),
                            Ident::from(parts[1]),
                        ]),
                    },
                );

View on GitHub (pinned to 6469eb736d)

Solutions

Run `SET iceberg_engine_connection = '<database>.<connection_name>';` in the same session before creating the table
Create the catalog connection first with `CREATE CONNECTION <name> WITH (type='iceberg', ...)` if it does not exist
Qualify the variable value correctly as `<database>.<connection_name>` — exactly one dot

Example fix

// before
CREATE TABLE t (...) WITH (engine = 'iceberg');
// after
SET iceberg_engine_connection = 'mydb.my_iceberg_conn';
CREATE TABLE t (...) WITH (engine = 'iceberg');

Defensive patterns

Strategy: validation

Validate before calling

-- run first; then only issue CREATE TABLE if a value is shown
SHOW iceberg_engine_connection;

Prevention

Always SET iceberg_engine_connection in the same session/script as Iceberg engine CREATE TABLE
Create the Iceberg connection before any DDL that references it
Include the SET statement in migration/bootstrap scripts and connection-pool init SQL

When it happens

Trigger: Running `CREATE TABLE ... WITH (engine = 'iceberg')` (or `CREATE TABLE ... CONNECTOR ... engine='iceberg'`) without first executing `SET iceberg_engine_connection = '<db>.<connection_name>'` in the session, or after resetting the variable.

Common situations: Developers new to Iceberg engine tables forget the two-step setup; running DDL from a fresh session, a BI tool connection pool, or a migration script where the SET was never issued; variable name typo so the real variable remains empty.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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