{"record":{"id":"16efa037625705b5","repo":"risingwavelabs/risingwave","slug":"enable-pk-index-is-only-supported-for-upsert-ice-16efa0","errorCode":null,"errorMessage":"`enable_pk_index` is only supported for upsert iceberg sink with merge-on-read mode","messagePattern":"`enable_pk_index` is only supported for upsert iceberg sink with merge-on-read mode","errorType":"validation","errorClass":"SinkError::Config","httpStatus":null,"severity":"error","filePath":"src/connector/src/sink/iceberg/config.rs","lineNumber":551,"sourceCode":"                 Please use 'merge-on-read' instead, which is strictly better for append-only workloads.\"\n            )));\n        }\n        Ok(())\n    }\n\n    pub(crate) fn validate_enable_pk_index(&self) -> Result<()> {\n        if !self.enable_pk_index {\n            return Ok(());\n        }\n\n        if self.r#type != SINK_TYPE_UPSERT {\n            return Err(SinkError::Config(anyhow!(\n                \"`enable_pk_index` is only supported for upsert iceberg sink\"\n            )));\n        }\n\n        if self.write_mode != IcebergWriteMode::MergeOnRead {\n            return Err(SinkError::Config(anyhow!(\n                \"`enable_pk_index` is only supported for upsert iceberg sink with merge-on-read mode\"\n            )));\n        }\n\n        if self.format_version < FormatVersion::V2 {\n            return Err(SinkError::Config(anyhow!(\n                \"`enable_pk_index` is only supported for upsert iceberg sink with format version >= 2\"\n            )));\n        }\n\n        if self.force_append_only {\n            return Err(SinkError::Config(anyhow!(\n                \"`enable_pk_index` cannot be true when `force_append_only` is true\"\n            )));\n        }\n\n        Ok(())\n    }","sourceCodeStart":533,"sourceCodeEnd":569,"githubUrl":"https://github.com/risingwavelabs/risingwave/blob/6469eb736d691e8e9b8a419a57edd6429ca77417/src/connector/src/sink/iceberg/config.rs#L533-L569","documentation":"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.","triggerScenarios":"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`.","commonSituations":"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.","solutions":["Change `write_mode = 'merge-on-read'` in the sink WITH options (MOR is also the recommended mode for upsert workloads in RisingWave).","Or disable `enable_pk_index` if copy-on-write mode must be kept."],"exampleFix":"-- before\nWITH (\n  connector = 'iceberg',\n  type = 'upsert',\n  write_mode = 'copy-on-write',\n  enable_pk_index = true\n);\n\n-- after\nWITH (\n  connector = 'iceberg',\n  type = 'upsert',\n  write_mode = 'merge-on-read',\n  enable_pk_index = true\n);","handlingStrategy":"validation","validationCode":"-- ensure upsert + merge-on-read when enable_pk_index = true\n-- required: type = 'upsert' AND write_mode = 'merge-on-read'","typeGuard":null,"tryCatchPattern":"-- on SinkError::Config, inspect the WITH clause; the message names the violated constraint","preventionTips":["Use `write_mode = 'merge-on-read'` as the default for upsert sinks.","Keep copy-on-write and pk-index flags in separate template variants.","Remember the checks are cumulative: type -> write_mode -> format_version -> force_append_only."],"tags":["iceberg","sink","write-mode","config-validation"],"backgroundTag":"conflicting-config-options","analyzedSha":"6469eb736d691e8e9b8a419a57edd6429ca77417","analyzedAt":"2026-09-11T21:06:21.487Z","contentChangedAt":"2026-09-11T21:06:21.487Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}