Iceberg engine table only supports with sink decouple, try…

Error message

Iceberg engine table only supports with sink decouple, try `set sink_decouple = true` to resolve it

What it means

`create_iceberg_engine_table` requires the session variable `sink_decouple` to be enabled. Iceberg engine tables write via the decoupled sink pipeline; with SinkDecouple::Disable the internal sink machinery is unavailable, so CREATE TABLE ... CONNECTOR = 'iceberg' is rejected and the user is told to SET sink_decouple = true.

Solutions

Run `SET sink_decouple = true;` in the session (or add it to the session config) before creating the Iceberg table.
Set sink_decouple = true as a default in risingwave.toml / cluster config so all sessions get it.
Retry the CREATE TABLE after enabling the flag.
If using a shared cluster, ask the admin to enable sink decouple at the system level (ALTER SYSTEM where available) rather than per session.

Example fix

// before
CREATE TABLE t CONNECTOR = 'iceberg' ...; -- fails when sink_decouple = false
// after
SET sink_decouple = true;
CREATE TABLE t CONNECTOR = 'iceberg' ...;

Defensive patterns

Strategy: validation

Validate before calling

// Check before creating Iceberg engine tables
const res = await client.query('SHOW VARIABLES WHERE name = \'sink_decouple\'');
if (res.rows[0]?.value !== 'true') await client.query('SET sink_decouple = true');

Try / catch

// Retry once after enabling the flag
try {
  await createIcebergTable();
} catch (e) {
  if (String(e).includes('sink decouple')) {
    await client.query('SET sink_decouple = true');
    await createIcebergTable();
  } else throw e;
}

Prevention

Enable sink_decouple = true in your cluster/session bootstrap script when using Iceberg engine tables.
Document the required session variable next to Iceberg DDL templates.
After version upgrades, re-verify config defaults against Iceberg requirements.
Catch this specific message in migration tooling and auto-apply the SET before retrying.

When it happens

Trigger: Executing CREATE TABLE with the Iceberg engine connector while the session has sink_decouple disabled (the default in some versions), i.e. matches!(sink_decouple, SinkDecouple::Disable) in create_iceberg_engine_table.

Common situations: Fresh sessions/clusters where sink_decouple was never enabled; clusters upgraded to an Iceberg-engine-capable version without updating the config; CI scripts using default session settings.

Related errors

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

Appendix: source

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

        .read_guard()
        .get_database_by_id(table.database_id)?
        .name()
        .to_owned();
    let rw_schema_name = session
        .env()
        .catalog_reader()
        .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 {

View on GitHub (pinned to 6469eb736d)