apache/seatunnel · error · SeaTunnelRuntimeException

CONFIG_VALIDATION_FAILED

CONFIG_VALIDATION_FAILED

Error message

table_options cannot be used together with a custom save_mode_create_template for StarRocks sink.

What it means

StarRocksSaveModeUtil.validateTableOptions enforces that when the user supplies table_options (key-value DDL options merged into CREATE TABLE), the sink does NOT also use a custom save_mode_create_template. Combining both is ambiguous (template vs generated options), so a CONFIG_VALIDATION_FAILED SeaTunnelRuntimeException is thrown.

Source

Thrown at seatunnel-connectors-v2/connector-starrocks/src/main/java/org/apache/seatunnel/connectors/seatunnel/starrocks/sink/StarRocksSaveModeUtil.java:66

    public String getCreateTableSql(
            String template,
            String database,
            String table,
            TableSchema tableSchema,
            String comment,
            String optionsKey,
            Map<String, String> tableOptions) {
        String createTableSql =
                getCreateTableSql(template, database, table, tableSchema, comment, optionsKey);
        return applyTableOptionsToCreateTableSql(createTableSql, tableOptions);
    }

    public void validateTableOptions(ReadonlyConfig config, Map<String, String> tableOptions) {
        if (tableOptions == null || tableOptions.isEmpty()) {
            return;
        }
        if (isCustomCreateTemplate(config)) {
            throw new SeaTunnelRuntimeException(
                    SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,
                    "table_options cannot be used together with a custom save_mode_create_template"
                            + " for StarRocks sink.");
        }
        for (Map.Entry<String, String> entry : tableOptions.entrySet()) {
            if (StringUtils.isBlank(entry.getKey())) {
                throw new SeaTunnelRuntimeException(
                        SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,
                        "table_options contains a blank property key for StarRocks sink.");
            }
            if (entry.getValue() == null) {
                throw new SeaTunnelRuntimeException(
                        SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,
                        String.format(
                                "table_options property '%s' has null value for StarRocks sink.",
                                entry.getKey()));
            }
        }

View on GitHub (pinned to cf67b549a7)

Solutions

Remove save_mode_create_template from the sink config and let table_options drive the generated DDL
Or remove table_options and keep full control via the custom template
Decide which mechanism owns CREATE TABLE details; only one may be used

Example fix

// before
sink = {
  save_mode_create_template = "CREATE TABLE (...)"
  table_options { replication_num = "3" }
}
// after
sink = {
  table_options { replication_num = "3" }
}

Defensive patterns

Strategy: validation

Validate before calling

if (cfg.containsKey("table_options") && cfg.containsKey("save_mode_create_template")) throw new IllegalArgumentException("Use either table_options or save_mode_create_template, not both");

Type guard

boolean usesOnlyOneCreationMechanism(ReadonlyConfig c) { return !(c.get(SaveModeCreateTemplate) != null && c.get(TableOptions) != null); }

Try / catch

try { buildSink(cfg); } catch (SeaTunnelRuntimeException e) { if (e.getErrorCode() == SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED && e.getMessage().contains("table_options cannot be used together")) { /* strip one of the two options and resubmit */ } throw e; }

Prevention

Choose one table-creation mechanism per sink config: template OR table_options
When migrating configs that add table_options, remove the old create template
Document the constraint in your internal config templates

When it happens

Trigger: Sink config containing both table_options entries and a non-default save_mode_create_template when auto table creation runs.

Common situations: Users copying an old config that had a custom create template and then adding table_options for partition/bucket tuning; upgrading SeaTunnel where table_options is newly supported while the old template remains in config.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/4851233256406b99. Report an issue: GitHub.