apache/seatunnel · error · SeaTunnelRuntimeException

COMMON-06

COMMON-06

Error message

illegal argument 'BigQuery CDC sequence number must not be null' of 'sequence_number_column'

What it means

The BigQuery CDC serializer requires a sequence number to order CDC events; encodeSequenceNumber throws this invalid-argument error (COMMON-06) when the value of the configured sequence number column is null. A null sequence number makes the record's ordering in BigQuery undefined, so the connector rejects it.

Solutions

Verify the sequence_number_column option names a column that exists in every CDC row and is populated.
Check the upstream CDC source for events with null sequence metadata (e.g. schema-change or heartbeat events) and filter them.
Coerce nullable sequence columns upstream (e.g. NVL/CASE) so a real numeric value always reaches the sink.
If using CDC heartbeat/watermark events, drop them before this sink.

Example fix

// before
"sequence_number_column" = "seq_no"   // column not present in upstream rows
// after: use the actual populated column
"sequence_number_column" = "binlog_pos"

Defensive patterns

Strategy: validation

Validate before calling

// before convert(), ensure the sequence value is present
Object seq = row.getField(sequenceFieldIndex);
if (seq == null) {
    throw new IllegalArgumentException("row missing sequence number for CDC");
}

Type guard

static boolean hasSequenceNumber(SeaTunnelRow row, int idx) {
    return idx >= 0 && idx < row.getArity() && row.getField(idx) != null;
}

Try / catch

try {
    sink.write(convert(row));
} catch (SeaTunnelConnectorException e) {
    if (e.getMessage().contains("sequence number must not be null")) {
        log.error("dropping CDC row with null sequence: {}", row); // or route to DLQ
        return;
    }
    throw e;
}

Prevention

Confirm sequence_number_column matches a populated column in every CDC event
Filter out CDC heartbeat/schema-change events that lack sequence metadata
Add a NOT NULL/default upstream so sequence values are always present
Test with real upstream CDC snapshots plus incremental events before production

When it happens

Trigger: convert() processes a CDC row whose sequence_number_column value is null — the upstream source did not populate the sequence field, or the configured column name points at a column that is absent/null in the row.

Common situations: Misconfigured sequence_number_column name so it maps to a missing column; upstream CDC source (e.g. MySQL/Postgres CDC) emitting rows where the sequence/op position field is null; schema mismatch after table evolution.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-bigquery/src/main/java/org/apache/seatunnel/connectors/bigquery/convert/BigQuerySerializer.java:117

                case UPDATE_BEFORE:
                    jsonObject.put(CHANGE_TYPE, "DELETE");
                    break;
                default:
                    throw CommonError.unsupportedOperation(
                            element.getRowKind().toString(), "Unsupported RowKind");
            }
            if (sequenceFieldIndex != -1) {
                jsonObject.put(
                        SEQUENCE_NUM, encodeSequenceNumber(element.getField(sequenceFieldIndex)));
            }
        }

        return jsonObject;
    }

    private String encodeSequenceNumber(Object value) {
        if (value == null) {
            throw invalidSequenceNumber("must not be null");
        }

        if (value instanceof Byte
                || value instanceof Short
                || value instanceof Integer
                || value instanceof Long) {
            return encodeIntegralSequenceNumber(BigInteger.valueOf(((Number) value).longValue()));
        }

        if (value instanceof BigDecimal) {
            try {
                return encodeIntegralSequenceNumber(((BigDecimal) value).toBigIntegerExact());
            } catch (ArithmeticException e) {
                throw invalidSequenceNumber("must not contain a fractional value");
            }
        }

        if (value instanceof String) {

View on GitHub (pinned to cf67b549a7)