risingwavelabs/risingwave · error · SinkError::Config

`enable_pk_index` is only supported for upsert iceberg sink

Error message

`enable_pk_index` is only supported for upsert iceberg sink with merge-on-read mode

What it means

This error is raised when `enable_pk_index = true` is set on an upsert Iceberg sink whose `write_mode` is not `merge-on-read`. The pk index is implemented only for the merge-on-read (MOR) writer, so copy-on-write (COW) mode cannot use it. The check appears in `validate_enable_pk_index` (src/connector/src/sink/iceberg/config.rs:550) after the sink-type check passes.

Source

Thrown at src/connector/src/sink/iceberg/config.rs:551

                 Please use 'merge-on-read' instead, which is strictly better for append-only workloads."
            )));
        }
        Ok(())
    }

    pub(crate) fn validate_enable_pk_index(&self) -> Result<()> {
        if !self.enable_pk_index {
            return Ok(());
        }

        if self.r#type != SINK_TYPE_UPSERT {
            return Err(SinkError::Config(anyhow!(
                "`enable_pk_index` is only supported for upsert iceberg sink"
            )));
        }

        if self.write_mode != IcebergWriteMode::MergeOnRead {
            return Err(SinkError::Config(anyhow!(
                "`enable_pk_index` is only supported for upsert iceberg sink with merge-on-read mode"
            )));
        }

        if self.format_version < FormatVersion::V2 {
            return Err(SinkError::Config(anyhow!(
                "`enable_pk_index` is only supported for upsert iceberg sink with format version >= 2"
            )));
        }

        if self.force_append_only {
            return Err(SinkError::Config(anyhow!(
                "`enable_pk_index` cannot be true when `force_append_only` is true"
            )));
        }

        Ok(())
    }

View on GitHub (pinned to 6469eb736d)

Solutions

1. Change `write_mode = 'merge-on-read'` in the sink WITH options (MOR is also the recommended mode for upsert workloads in RisingWave).
2. Or disable `enable_pk_index` if copy-on-write mode must be kept.

Example fix

-- before
WITH (
  connector = 'iceberg',
  type = 'upsert',
  write_mode = 'copy-on-write',
  enable_pk_index = true
);

-- after
WITH (
  connector = 'iceberg',
  type = 'upsert',
  write_mode = 'merge-on-read',
  enable_pk_index = true
);

-- ensure upsert + merge-on-read when enable_pk_index = true
-- required: type = 'upsert' AND write_mode = 'merge-on-read'

-- on SinkError::Config, inspect the WITH clause; the message names the violated constraint

When it happens

Trigger: Creating an Iceberg upsert sink with `enable_pk_index = true` and `write_mode = 'copy-on-write'` (or any write mode other than `merge-on-read`). Fails during sink config construction via `validate_enable_pk_index`.

Common situations: Users who previously chose copy-on-write mode and later enable the pk index; templates that pin `write_mode = 'copy-on-write'` for other reasons; misunderstanding that MOR is required for the feature.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• `enable_pk_index` is only supported for upsert iceberg sink
• `enable_pk_index` is only supported for upsert iceberg sink
• `enable_pk_index` cannot be true when `force_append_only` is
• `{}` must be {}, or {}
• `primary-key` must not be empty in {}

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