{"record":{"id":"59fe3c2c4f3f75a0","repo":"risingwavelabs/risingwave","slug":"creating-an-iceberg-table-with-variant-column","errorCode":null,"errorMessage":"creating an Iceberg table with VARIANT column `{}` requires `format_version = '3'`","messagePattern":"creating an Iceberg table with VARIANT column `(.+?)` requires `format_version = '3'`","errorType":"validation","errorClass":"SinkError::Config","httpStatus":null,"severity":"error","filePath":"src/connector/src/sink/iceberg/create_table.rs","lineNumber":123,"sourceCode":"    let namespace = table_id.namespace().clone();\n    let table_name = table_id.name().to_owned();\n    create_namespace_if_not_exists(catalog.as_ref(), &namespace).await?;\n\n    if catalog\n        .table_exists(&table_id)\n        .await\n        .map_err(|e| SinkError::Iceberg(anyhow!(e)))?\n    {\n        return Ok(false);\n    }\n\n    if config.table_format_version() < FormatVersion::V3\n        && let Some(column) = param\n            .columns\n            .iter()\n            .find(|column| column.data_type.contains_variant())\n    {\n        return Err(SinkError::Config(anyhow!(\n            \"creating an Iceberg table with VARIANT column `{}` requires `format_version = '3'`\",\n            column.name\n        )));\n    }\n\n    let iceberg_create_table_arrow_convert = IcebergCreateTableArrowConvert::default();\n    // convert risingwave schema -> arrow schema -> iceberg schema\n    let arrow_fields = param\n        .columns\n        .iter()\n        .map(|column| {\n            Ok(iceberg_create_table_arrow_convert\n                .to_arrow_field(&column.name, &column.data_type)\n                .map_err(|e| SinkError::Iceberg(anyhow!(e)))\n                .context(format!(\n                    \"failed to convert {}: {} to arrow type\",\n                    column.name, column.data_type\n                ))?)","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/risingwavelabs/risingwave/blob/6469eb736d691e8e9b8a419a57edd6429ca77417/src/connector/src/sink/iceberg/create_table.rs#L105-L141","documentation":"RisingWave's VARIANT data type can only be stored in Iceberg tables using the Iceberg spec's Variant type, which requires format version 3. If the sink config specifies a lower table format version and any sink column contains a VARIANT type, creation is rejected with this configuration error before any catalog call.","triggerScenarios":"create_table_if_not_exists_impl finds a column whose data_type contains_variant() while config.table_format_version() < FormatVersion::V3 — i.e. a VARIANT column in the sink plus missing or older `table.format-version` ('1' or '2').","commonSituations":"User sinks a table containing a JSONB/VARIANT column but leaves format-version at the default; copy-pasted sink config written before VARIANT support; older Iceberg REST catalogs that don't support v3 specs.","solutions":["Set `table.format-version = '3'` in the sink WITH options.","Remove or cast the VARIANT column to a supported type (e.g. VARCHAR) if version 3 is unavailable.","Verify the target catalog/storage supports Iceberg format v3 before upgrading.","Recreate the sink after updating the config."],"exampleFix":"// before\nCREATE SINK s FROM mv WITH (connector='iceberg', table.format-version='2', ...);\n// after\nCREATE SINK s FROM mv WITH (connector='iceberg', table.format-version='3', ...);","handlingStrategy":"validation","validationCode":"// Pre-check: any VARIANT column requires format-version 3\nlet needs_v3 = param.columns.iter().any(|c| c.data_type.contains_variant());\nif needs_v3 && config.table_format_version() < FormatVersion::V3 {\n    eprintln!(\"set table.format-version = '3' for VARIANT columns\");\n}","typeGuard":null,"tryCatchPattern":"match result {\n    Err(SinkError::Config(e)) if e.to_string().contains(\"VARIANT\") => {\n        // recreate sink with table.format-version='3'\n    }\n    other => other?,\n}","preventionTips":["Always set table.format-version='3' when sinking JSONB/VARIANT columns.","Confirm the target catalog/storage supports Iceberg format v3.","Keep sink configs reviewed when adding VARIANT columns to source tables."],"tags":["rust","iceberg","variant","config"],"backgroundTag":"invalid-config-value","analyzedSha":"6469eb736d691e8e9b8a419a57edd6429ca77417","analyzedAt":"2026-09-11T21:06:21.487Z","contentChangedAt":"2026-09-11T21:06:21.487Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}