apache/seatunnel · error · OptionValidationException

oracle_insert_mode=APPEND_VALUES does not support…

Error message

oracle_insert_mode=APPEND_VALUES does not support exactly-once.

What it means

The validator rejects oracle_insert_mode=APPEND_VALUES together with is_exactly_once=true. APPEND_VALUES hint inserts are not compatible with SeaTunnel's exactly-once (XA) delivery for Oracle, so the combination is a configuration error caught at option validation time.

Solutions

  1. Set is_exactly_once=false (accepting at-least-once), or
  2. Use a different oracle_insert_mode that supports XA-based exactly-once
  3. If exactly-once is required, consider a database that supports the connector's XA path properly

Example fix

// before
oracle_insert_mode = "append_values"
is_exactly_once = true
// after
oracle_insert_mode = "append_values"
is_exactly_once = false
Defensive patterns

Strategy: validation

Validate before calling

if ("append_values".equalsIgnoreCase(config.get("oracle_insert_mode"))
    && Boolean.parseBoolean(String.valueOf(config.get("is_exactly_once")))) {
  throw new IllegalArgumentException("append_values does not support exactly-once");
}

Try / catch

try {
  validateSinkOptions(config);
} catch (OptionValidationException e) {
  // drop is_exactly_once or change insert mode
}

Prevention

When it happens

Trigger: Sink configured with oracle_insert_mode="append_values" and is_exactly_once=true; evaluate() throws OptionValidationException at JdbcSinkFactory.java:424.

Common situations: Users wanting both high-performance bulk inserts and exactly-once semantics; config copied from an exactly-once MySQL/PostgreSQL job onto an Oracle sink with append_values mode.

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/f20806f1bb998772. 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:424

            return "oracle_insert_mode=APPEND_VALUES conflicts with certain options";
        }

        @Override
        public boolean evaluate(ReadonlyConfig config, JdbcSinkConfig.OracleInsertMode value)
                throws OptionValidationException {
            if (value != JdbcSinkConfig.OracleInsertMode.APPEND_VALUES) {
                return true;
            }
            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

View on GitHub (pinned to cf67b549a7)