You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@seatunnel.apache.org by gi...@apache.org on 2026/08/26 14:31:35 UTC

(seatunnel) 01/01: [Improve][Connector-V2][Iceberg]Migrate config validation to declarative OptionRule (#11921)

This is an automated email from the ASF dual-hosted git repository.

github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/dev/pr-11921-8725e1e1372c65f871830eb5f8ca2a0551d73504
in repository https://gitbox.apache.org/repos/asf/seatunnel.git

commit 4f0b735de7da66775e1bb7cc035f46f3a21517ef
Author: Claire <cl...@163.com>
AuthorDate: Wed Aug 26 14:31:24 2026 +0000

    [Improve][Connector-V2][Iceberg]Migrate config validation to declarative OptionRule (#11921)
---
 docs/en/connectors/source/Iceberg.md               |  2 +-
 docs/zh/connectors/source/Iceberg.md               |  2 +-
 .../iceberg/config/IcebergSinkConfig.java          | 15 -----
 .../iceberg/config/IcebergSinkOptions.java         |  5 +-
 .../seatunnel/iceberg/sink/IcebergSinkFactory.java |  9 +++
 .../iceberg/source/IcebergSourceFactory.java       |  6 +-
 .../seatunnel/iceberg/IcebergFactoryTest.java      | 76 ++++++++++++++++++++++
 .../seatunnel/iceberg/utils/SchemaUtilsTest.java   | 28 --------
 .../e2e/connector/iceberg/IcebergValidationIT.java | 58 +++++++++++++++++
 ...eberg-validation-nonpositive-scan-interval.conf | 44 +++++++++++++
 .../iceberg-validation-upsert-without-pk.conf      | 52 +++++++++++++++
 11 files changed, 250 insertions(+), 47 deletions(-)

diff --git a/docs/en/connectors/source/Iceberg.md b/docs/en/connectors/source/Iceberg.md
index 338bbe1936..0023ca635f 100644
--- a/docs/en/connectors/source/Iceberg.md
+++ b/docs/en/connectors/source/Iceberg.md
@@ -90,7 +90,7 @@ libfb303-xxx.jar
 | use_snapshot_id          | long    | no       | -                    | Instructs this scan to look for use the given snapshot ID.                                                                                                                                                                                                                                                                                                                                                                          [...]
 | use_snapshot_timestamp   | long    | no       | -                    | Instructs this scan to look for use the most recent snapshot as of the given time in milliseconds. timestamp – the timestamp in millis since the Unix epoch                                                                                                                                                                                                                                                                         [...]
 | stream_scan_strategy     | enum    | no       | FROM_LATEST_SNAPSHOT | Starting strategy for stream mode execution, Default to use `FROM_LATEST_SNAPSHOT` if don't specify any value,The optional values are:<br/>TABLE_SCAN_THEN_INCREMENTAL: Do a regular table scan then switch to the incremental mode.<br/>FROM_LATEST_SNAPSHOT: Start incremental mode from the latest snapshot inclusive.<br/>FROM_EARLIEST_SNAPSHOT: Start incremental mode from the earliest snapshot inclusive.<br/>FROM_SNAPSHO [...]
-| increment.scan-interval  | long    | no       | 2000                 | The interval of increment scan(mills)                                                                                                                                                                                                                                                                                                                                                                                               [...]
+| increment.scan-interval  | long    | no       | 2000                 | The interval of increment scan(mills). Must be a positive value.                                                                                                                                                                                                                                                                                                                                                                    [...]
 | common-options           |         | no       | -                    | Source plugin common parameters, please refer to [Source Common Options](../common-options/source-common-options.md) for details.                                                                                                                                                                                                                                                                                                   [...]
 | query                    | String  | no       | -                    | The select DML used to filter or project Iceberg data. Use the literal placeholder table name `table`, and do not use table aliases. For example: `select * from table where f1 > 100`, `select fn from table where f1 > 100`. The current LIKE support is limited: the LIKE pattern should not start with `%`; for example, `select f1 from table where f2 like 'tom%'` is supported.                                              [...]
 | krb5_path                              | string  | no       | /etc/krb5.conf              | The path to the `krb5.conf` file for Kerberos authentication.                                                                                                                                                                                                                                                                |
diff --git a/docs/zh/connectors/source/Iceberg.md b/docs/zh/connectors/source/Iceberg.md
index 11797afc85..482882648b 100644
--- a/docs/zh/connectors/source/Iceberg.md
+++ b/docs/zh/connectors/source/Iceberg.md
@@ -90,7 +90,7 @@ libfb303-xxx.jar
 | use_snapshot_id          | long    | 否   | -                    | 指示此扫描使用给定的快照 ID。                                                                                                                                                                                                                                                                                                                                                                                                                         [...]
 | use_snapshot_timestamp   | long    | 否   | -                    | 指示此扫描使用给定时间(毫秒)的最新快照。timestamp – 自 Unix 纪元以来的时间戳(毫秒)                                                                                                                                                                                                                                                                                                                                                            |
 | stream_scan_strategy     | enum    | 否   | FROM_LATEST_SNAPSHOT | 流模式执行的启动策略,如果不指定任何值,默认使用 `FROM_LATEST_SNAPSHOT`,可选值为:<br/>TABLE_SCAN_THEN_INCREMENTAL:执行常规表扫描,然后切换到增量模式。<br/>FROM_LATEST_SNAPSHOT:从最新快照(包含)开始增量模式。<br/>FROM_EARLIEST_SNAPSHOT:从最早快照(包含)开始增量模式。<br/>FROM_SNAPSHOT_ID:从具有特定 id(包含)的快照开始增量模式。<br/>FROM_SNAPSHOT_TIMESTAMP:从具有特定时间戳(包含)的快照开始增量模式。 |
-| increment.scan-interval  | long    | 否   | 2000                 | 增量扫描的间隔(毫秒)                                                                                                                                                                                                                                                                                                                                                                                                                              [...]
+| increment.scan-interval  | long    | 否   | 2000                 | 增量扫描的间隔(毫秒),必须为正数                                                                                                                                                                                                                                                                                                                                                                                                                        [...]
 | common-options           |         | 否   | -                    | 源插件通用参数,请参考 [源通用选项](../common-options/source-common-options.md) 详见。                                                                                                                                                                                                                                                                                                                                                                      [...]
 | query                    | String  | 否   | -                    | 用于过滤或投影 Iceberg 数据的 select DML。这里使用固定占位表名 `table`,不要写真实表名,也不支持表别名。例如:`select * from table where f1 > 100`、`select fn from table where f1 > 100`。当前对 LIKE 语法的支持有限:LIKE 模式不应以 `%` 开头,例如 `select f1 from table where f2 like 'tom%'`。                                                                                                                                                                                                       [...]
 | krb5_path                              | string  | no       | /etc/krb5.conf              | `krb5.conf` 文件的路径,用于 Kerberos 认证。                                                                                                                                                                                                                                                                |
diff --git a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkConfig.java b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkConfig.java
index 4fa9806eeb..6567208e4e 100644
--- a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkConfig.java
+++ b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkConfig.java
@@ -81,21 +81,6 @@ public class IcebergSinkConfig extends IcebergCommonConfig {
         this.dataSaveMode = readonlyConfig.get(IcebergSinkOptions.DATA_SAVE_MODE);
         this.dataSaveModeSQL = readonlyConfig.get(IcebergSinkOptions.DATA_SAVE_MODE_CUSTOM_SQL);
         this.commitBranch = readonlyConfig.get(IcebergSinkOptions.TABLES_DEFAULT_COMMIT_BRANCH);
-        if (this.upsertModeEnabled
-                && readonlyConfig
-                        .getOptional(IcebergSinkOptions.TABLE_PRIMARY_KEYS)
-                        .map(String::trim)
-                        .map(String::isEmpty)
-                        .orElse(true)) {
-            throw new IllegalArgumentException(
-                    String.format(
-                            "'%s' is enabled but '%s' is not explicitly configured. "
-                                    + "Upsert mode requires an explicit primary-key list. "
-                                    + "The source table primary key is no longer inherited "
-                                    + "automatically (see: apache/seatunnel#10747).",
-                            IcebergSinkOptions.TABLE_UPSERT_MODE_ENABLED_PROP.key(),
-                            IcebergSinkOptions.TABLE_PRIMARY_KEYS.key()));
-        }
     }
 
     @VisibleForTesting
diff --git a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkOptions.java b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkOptions.java
index 8557b90374..38204b042b 100644
--- a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkOptions.java
+++ b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/config/IcebergSinkOptions.java
@@ -55,7 +55,10 @@ public class IcebergSinkOptions extends IcebergCommonOptions {
                     .stringType()
                     .noDefaultValue()
                     .withDescription(
-                            "Default comma-separated list of columns that identify a row in tables (primary key)");
+                            "Default comma-separated list of columns that identify a row in tables (primary key). "
+                                    + "Required and must be non-blank when 'iceberg.table.upsert-mode-enabled' is true: "
+                                    + "upsert mode needs an explicit primary-key list because the source table primary key "
+                                    + "is no longer inherited automatically (see: apache/seatunnel#10747)");
 
     public static final Option<String> TABLE_DEFAULT_PARTITION_KEYS =
             Options.key("iceberg.table.partition-keys")
diff --git a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/sink/IcebergSinkFactory.java b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/sink/IcebergSinkFactory.java
index f71aa440db..1eb1e4c8dd 100644
--- a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/sink/IcebergSinkFactory.java
+++ b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/sink/IcebergSinkFactory.java
@@ -20,6 +20,7 @@ package org.apache.seatunnel.connectors.seatunnel.iceberg.sink;
 import org.apache.seatunnel.shade.org.apache.commons.lang3.StringUtils;
 
 import org.apache.seatunnel.api.configuration.ReadonlyConfig;
+import org.apache.seatunnel.api.configuration.util.Conditions;
 import org.apache.seatunnel.api.configuration.util.OptionRule;
 import org.apache.seatunnel.api.options.SinkConnectorCommonOptions;
 import org.apache.seatunnel.api.sink.DataSaveMode;
@@ -71,6 +72,14 @@ public class IcebergSinkFactory implements TableSinkFactory {
                         IcebergSinkOptions.DATA_SAVE_MODE,
                         DataSaveMode.CUSTOM_PROCESSING,
                         IcebergSinkOptions.DATA_SAVE_MODE_CUSTOM_SQL)
+                .conditional(
+                        IcebergSinkOptions.TABLE_UPSERT_MODE_ENABLED_PROP,
+                        true,
+                        IcebergSinkOptions.TABLE_PRIMARY_KEYS)
+                .conditional(
+                        IcebergSinkOptions.TABLE_UPSERT_MODE_ENABLED_PROP,
+                        true,
+                        Conditions.notBlank(IcebergSinkOptions.TABLE_PRIMARY_KEYS))
                 .build();
     }
 
diff --git a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/source/IcebergSourceFactory.java b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/source/IcebergSourceFactory.java
index 49538f6905..029bc313f3 100644
--- a/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/source/IcebergSourceFactory.java
+++ b/seatunnel-connectors-v2/connector-iceberg/src/main/java/org/apache/seatunnel/connectors/seatunnel/iceberg/source/IcebergSourceFactory.java
@@ -18,6 +18,7 @@
 package org.apache.seatunnel.connectors.seatunnel.iceberg.source;
 
 import org.apache.seatunnel.api.configuration.ReadonlyConfig;
+import org.apache.seatunnel.api.configuration.util.Conditions;
 import org.apache.seatunnel.api.configuration.util.OptionRule;
 import org.apache.seatunnel.api.options.ConnectorCommonOptions;
 import org.apache.seatunnel.api.source.SeaTunnelSource;
@@ -70,12 +71,15 @@ public class IcebergSourceFactory implements TableSourceFactory {
                         IcebergSourceOptions.KEY_USE_SNAPSHOT_ID,
                         IcebergSourceOptions.KEY_USE_SNAPSHOT_TIMESTAMP,
                         IcebergSourceOptions.KEY_STREAM_SCAN_STRATEGY,
-                        IcebergSourceOptions.KEY_INCREMENT_SCAN_INTERVAL,
                         IcebergCommonOptions.HADOOP_PROPS,
                         IcebergSourceOptions.HADOOP_CONF_PATH_PROP,
                         IcebergCommonOptions.KERBEROS_PRINCIPAL,
                         IcebergCommonOptions.KERBEROS_KEYTAB_PATH,
                         IcebergCommonOptions.KRB5_PATH)
+                .optional(
+                        IcebergSourceOptions.KEY_INCREMENT_SCAN_INTERVAL,
+                        Conditions.greaterThan(
+                                IcebergSourceOptions.KEY_INCREMENT_SCAN_INTERVAL, 0L))
                 .build();
     }
 
diff --git a/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/IcebergFactoryTest.java b/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/IcebergFactoryTest.java
index 939dbb9c44..ef201bdffb 100644
--- a/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/IcebergFactoryTest.java
+++ b/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/IcebergFactoryTest.java
@@ -31,6 +31,8 @@ import org.apache.seatunnel.connectors.seatunnel.iceberg.source.IcebergSourceFac
 
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 
 import java.util.Arrays;
 import java.util.Collections;
@@ -99,6 +101,31 @@ class IcebergFactoryTest {
                 absolutelyRequiredOptions(SINK_RULE).contains(IcebergSinkOptions.CATALOG_PROPS));
     }
 
+    @Test
+    void sinkUpsertConditionallyRequiresPrimaryKeys() {
+        boolean hasConditional =
+                SINK_RULE.getRequiredOptions().stream()
+                        .filter(o -> o instanceof RequiredOption.ConditionalRequiredOptions)
+                        .anyMatch(
+                                o ->
+                                        o.getOptions()
+                                                .contains(IcebergSinkOptions.TABLE_PRIMARY_KEYS));
+        Assertions.assertTrue(hasConditional);
+    }
+
+    @Test
+    void sourceScanIntervalHasValueConstraint() {
+        boolean hasConstraint =
+                SOURCE_RULE.getValueConstraints().stream()
+                        .anyMatch(
+                                c ->
+                                        c.getOption()
+                                                .equals(
+                                                        IcebergSourceOptions
+                                                                .KEY_INCREMENT_SCAN_INTERVAL));
+        Assertions.assertTrue(hasConstraint);
+    }
+
     // accepted configs
 
     @Test
@@ -132,6 +159,30 @@ class IcebergFactoryTest {
         Assertions.assertDoesNotThrow(() -> validateSink(config));
     }
 
+    @Test
+    void sinkUpsertWithPrimaryKeysValid() {
+        Map<String, Object> config = new HashMap<>();
+        config.put("iceberg.catalog.config", catalogProps());
+        config.put("iceberg.table.upsert-mode-enabled", true);
+        config.put("iceberg.table.primary-keys", "id");
+        Assertions.assertDoesNotThrow(() -> validateSink(config));
+    }
+
+    @Test
+    void sinkNoUpsertWithoutPrimaryKeysValid() {
+        Map<String, Object> config = new HashMap<>();
+        config.put("iceberg.catalog.config", catalogProps());
+        config.put("iceberg.table.upsert-mode-enabled", false);
+        Assertions.assertDoesNotThrow(() -> validateSink(config));
+    }
+
+    @Test
+    void sourcePositiveScanIntervalValid() {
+        Map<String, Object> config = sourceConfigWithTable();
+        config.put("increment.scan-interval", 2000L);
+        Assertions.assertDoesNotThrow(() -> validateSource(config));
+    }
+
     // rejected configs
 
     @Test
@@ -163,6 +214,31 @@ class IcebergFactoryTest {
         Assertions.assertThrows(OptionValidationException.class, () -> validateSink(config));
     }
 
+    @Test
+    void sinkUpsertWithoutPrimaryKeysRejected() {
+        Map<String, Object> config = new HashMap<>();
+        config.put("iceberg.catalog.config", catalogProps());
+        config.put("iceberg.table.upsert-mode-enabled", true);
+        Assertions.assertThrows(OptionValidationException.class, () -> validateSink(config));
+    }
+
+    @Test
+    void sinkUpsertWithBlankPrimaryKeysRejected() {
+        Map<String, Object> config = new HashMap<>();
+        config.put("iceberg.catalog.config", catalogProps());
+        config.put("iceberg.table.upsert-mode-enabled", true);
+        config.put("iceberg.table.primary-keys", "  ");
+        Assertions.assertThrows(OptionValidationException.class, () -> validateSink(config));
+    }
+
+    @ParameterizedTest
+    @ValueSource(longs = {0L, -1L})
+    void sourceNonPositiveScanIntervalRejected(long interval) {
+        Map<String, Object> config = sourceConfigWithTable();
+        config.put("increment.scan-interval", interval);
+        Assertions.assertThrows(OptionValidationException.class, () -> validateSource(config));
+    }
+
     // helpers
 
     /**
diff --git a/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/utils/SchemaUtilsTest.java b/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/utils/SchemaUtilsTest.java
index 030e2fc66d..274d53047e 100644
--- a/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/utils/SchemaUtilsTest.java
+++ b/seatunnel-connectors-v2/connector-iceberg/src/test/java/org/apache/seatunnel/connectors/seatunnel/iceberg/utils/SchemaUtilsTest.java
@@ -172,34 +172,6 @@ class SchemaUtilsTest {
                         + "and causes positional deletes in append-only CDC pipelines.");
     }
 
-    /**
-     * Guard against the regression introduced by the SchemaUtils PK-fallback fix: when {@code
-     * iceberg.table.upsert-mode-enabled=true} is set without an explicit {@code
-     * iceberg.table.primary-keys}, the sink must fail fast with a clear error rather than silently
-     * creating a delta writer with an empty identifier-field set (which would produce broken upsert
-     * semantics).
-     */
-    @Test
-    void testIcebergSinkConfigThrowsWhenUpsertModeEnabledWithoutPrimaryKeys() {
-        ReadonlyConfig config =
-                ReadonlyConfig.fromMap(
-                        new HashMap<String, Object>() {
-                            {
-                                put(IcebergSinkOptions.TABLE_UPSERT_MODE_ENABLED_PROP.key(), true);
-                                // iceberg.table.primary-keys deliberately absent
-                            }
-                        });
-        IllegalArgumentException ex =
-                Assertions.assertThrows(
-                        IllegalArgumentException.class,
-                        () -> new IcebergSinkConfig(config),
-                        "IcebergSinkConfig must reject upsert-mode-enabled=true without an "
-                                + "explicit iceberg.table.primary-keys configuration");
-        Assertions.assertTrue(
-                ex.getMessage().contains(IcebergSinkOptions.TABLE_PRIMARY_KEYS.key()),
-                "Error message should name the missing config key");
-    }
-
     /**
      * Regression test for the catalog-path CatalogTable PK fallback.
      *
diff --git a/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/java/org/apache/seatunnel/e2e/connector/iceberg/IcebergValidationIT.java b/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/java/org/apache/seatunnel/e2e/connector/iceberg/IcebergValidationIT.java
new file mode 100644
index 0000000000..c29ab67ba1
--- /dev/null
+++ b/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/java/org/apache/seatunnel/e2e/connector/iceberg/IcebergValidationIT.java
@@ -0,0 +1,58 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.seatunnel.e2e.connector.iceberg;
+
+import org.apache.seatunnel.e2e.common.TestSuiteBase;
+import org.apache.seatunnel.e2e.common.container.TestContainer;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.TestTemplate;
+import org.testcontainers.containers.Container;
+
+import lombok.extern.slf4j.Slf4j;
+
+import java.io.IOException;
+
+@Slf4j
+public class IcebergValidationIT extends TestSuiteBase {
+
+    @TestTemplate
+    public void testSinkUpsertWithoutPrimaryKeysRejected(TestContainer container)
+            throws IOException, InterruptedException {
+        Container.ExecResult execResult =
+                container.executeJob("/iceberg/iceberg-validation-upsert-without-pk.conf");
+        Assertions.assertNotEquals(0, execResult.getExitCode());
+        String stderr = execResult.getStderr();
+        Assertions.assertNotNull(stderr, "stderr should not be null");
+        Assertions.assertTrue(
+                stderr.contains("Option validation failed") && stderr.contains("primary-keys"),
+                "stderr should report the failed primary-keys validation, but was: " + stderr);
+    }
+
+    @TestTemplate
+    public void testSourceNonPositiveScanIntervalRejected(TestContainer container)
+            throws IOException, InterruptedException {
+        Container.ExecResult execResult =
+                container.executeJob("/iceberg/iceberg-validation-nonpositive-scan-interval.conf");
+        Assertions.assertNotEquals(0, execResult.getExitCode());
+        String stderr = execResult.getStderr();
+        Assertions.assertNotNull(stderr, "stderr should not be null");
+        Assertions.assertTrue(
+                stderr.contains("Option validation failed") && stderr.contains("scan-interval"),
+                "stderr should report the failed scan-interval validation, but was: " + stderr);
+    }
+}
diff --git a/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/resources/iceberg/iceberg-validation-nonpositive-scan-interval.conf b/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/resources/iceberg/iceberg-validation-nonpositive-scan-interval.conf
new file mode 100644
index 0000000000..82db5a5582
--- /dev/null
+++ b/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/resources/iceberg/iceberg-validation-nonpositive-scan-interval.conf
@@ -0,0 +1,44 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# Negative case for declarative validation (#11007): `increment.scan-interval` must be
+# a positive number of milliseconds, so a value of 0 must be rejected at submission time
+# by IcebergSourceFactory.optionRule() before any catalog is touched. No Iceberg
+# environment is required.
+
+env {
+  parallelism = 1
+  job.mode = "BATCH"
+}
+
+source {
+  Iceberg {
+    catalog_name = "seatunnel_test"
+    iceberg.catalog.config = {
+      "type" = "hadoop"
+      "warehouse" = "file:///tmp/seatunnel_mnt/iceberg/hadoop-source/"
+    }
+    namespace = "seatunnel_namespace"
+    table = "iceberg_source_table"
+    increment.scan-interval = 0
+  }
+}
+
+sink {
+  Console {
+  }
+}
diff --git a/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/resources/iceberg/iceberg-validation-upsert-without-pk.conf b/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/resources/iceberg/iceberg-validation-upsert-without-pk.conf
new file mode 100644
index 0000000000..4b53c6f278
--- /dev/null
+++ b/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-iceberg-e2e/src/test/resources/iceberg/iceberg-validation-upsert-without-pk.conf
@@ -0,0 +1,52 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# Negative case for declarative validation (#11007): `iceberg.table.upsert-mode-enabled`
+# is true but `iceberg.table.primary-keys` is not configured, so the job must be rejected
+# at submission time by IcebergSinkFactory.optionRule() before any catalog is touched.
+# No Iceberg environment is required.
+
+env {
+  parallelism = 1
+  job.mode = "BATCH"
+}
+
+source {
+  FakeSource {
+    row.num = 10
+    schema = {
+      fields {
+        id = int
+        name = string
+      }
+    }
+    plugin_output = "fake"
+  }
+}
+
+sink {
+  Iceberg {
+    catalog_name = "seatunnel_test"
+    iceberg.catalog.config = {
+      "type" = "hadoop"
+      "warehouse" = "file:///tmp/seatunnel_mnt/iceberg/hadoop-sink/"
+    }
+    namespace = "seatunnel_namespace"
+    table = "iceberg_sink_table"
+    iceberg.table.upsert-mode-enabled = true
+  }
+}