apache/seatunnel · error · OptionValidationException

oracle_insert_mode=APPEND_VALUES does not support custom…

Error message

oracle_insert_mode=APPEND_VALUES does not support custom query.

What it means

The validator rejects oracle_insert_mode=APPEND_VALUES when generate_sink_sql=false, i.e. when a custom query is used. APPEND_VALUES hint generation only works with the connector's auto-generated INSERT statements, not user-supplied SQL.

Solutions

Remove the custom query and let the connector generate SQL (table-based sink), or
Switch oracle_insert_mode away from append_values when using a custom query

Example fix

// before
oracle_insert_mode = "append_values"
query = "INSERT INTO t SELECT ..."
// after
# custom query sink: use default insert mode
query = "INSERT INTO t SELECT ..."

Defensive patterns

Strategy: validation

Validate before calling

if ("append_values".equalsIgnoreCase(config.get("oracle_insert_mode"))
    && config.get("query") != null) {
  throw new IllegalArgumentException("append_values requires generated SQL, not a custom query");
}

Try / catch

try {
  validateSinkOptions(config);
} catch (OptionValidationException e) {
  // remove custom query or switch insert mode
}

Prevention

Use table-based sinks (generated SQL) with APPEND_VALUES
When a custom query is needed, use the default insert mode
Check that generate_sink_sql is true when relying on APPEND_VALUES

When it happens

Trigger: Sink configured with oracle_insert_mode="append_values" plus a custom query (query option) instead of table-based generated SQL; generate_sink_sql is false so evaluate() throws at JdbcSinkFactory.java:432.

Common situations: Users writing custom INSERT ... SELECT or upsert queries for Oracle while keeping append_values mode; configs migrated from generated-SQL jobs to custom-query jobs.

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

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/sink/JdbcSinkFactory.java:432

            }
            if (config.get(JdbcSinkOptions.USE_COPY_STATEMENT)) {
                throw new OptionValidationException(
                        "oracle_insert_mode=APPEND_VALUES does not support copy statement.");
            }
            if (config.get(JdbcSinkOptions.IS_EXACTLY_ONCE)) {
                throw new OptionValidationException(
                        "oracle_insert_mode=APPEND_VALUES does not support exactly-once.");
            }
            if (!config.get(JdbcSinkOptions.AUTO_COMMIT)) {
                throw new OptionValidationException(
                        "oracle_insert_mode=APPEND_VALUES requires auto_commit=true.");
            }
            if (!config.get(JdbcSinkOptions.GENERATE_SINK_SQL)) {
                throw new OptionValidationException(
                        "oracle_insert_mode=APPEND_VALUES does not support custom query.");
            }
            if (config.get(JdbcSinkOptions.SUPPORT_UPSERT_BY_INSERT_ONLY)) {
                throw new OptionValidationException(
                        "oracle_insert_mode=APPEND_VALUES does not support insert-only upsert.");
            }
            return true;
        }
    }

    /**
     * Submission-time validator for {@code is_exactly_once=true}.
     *
     * <p>JDBC XA sink does not support retries; {@code max_retries} must be 0 when exactly-once is
     * enabled, otherwise duplicates may occur.
     */
    static class ExactlyOnceMaxRetriesValidator implements ConditionExtension<Boolean> {
        @Override
        public String description() {
            return "is_exactly_once=true requires max_retries=0";
        }

View on GitHub (pinned to cf67b549a7)