apache/seatunnel · error · SeaTunnelRuntimeException

BigQuery CDC sequence number each section must contain at…

Error message

BigQuery CDC sequence number each section must contain at most 16 characters

What it means

Every section of a String-encoded CDC sequence number may hold at most 16 hexadecimal characters (64 bits per section); longer sections cannot map to the unsigned-64-per-slot encoding and are rejected by validateSequenceSection.

Solutions

Split long hex strings into <=16-character sections, e.g. "aabb..." (32 chars) becomes first16 + "/" + last16.
Truncate or hash the value to 64 bits if only one 64-bit slot is intended.
Regenerate the sequence number from the source's raw integral fields instead of importing a foreign pre-encoded hex string.
Validate inputs with regex ^[0-9A-Fa-f]{1,16}(/[0-9A-Fa-f]{1,16}){0,3}$ before the job runs.

Example fix

// before
String seq = "0123456789ABCDEF0123456789ABCDEF"; // 32 chars in one section
// after
String seq = "0123456789ABCDEF/0123456789ABCDEF"; // split into 16-char sections

Defensive patterns

Strategy: validation

Validate before calling

boolean ok = seq.matches("^[0-9A-Fa-f]{1,16}(/[0-9A-Fa-f]{1,16}){0,3}$"); if (!ok) { throw new IllegalArgumentException("sequence number sections must be 1-16 hex chars, max 4 sections: " + seq); }

Prevention

Split hex strings longer than 16 chars into 16-char sections.
Validate the format with a regex at pipeline-configuration time.
Document the sectioning rule for any producer of these values.

When it happens

Trigger: A '/'-separated section with length > 16 is passed to encodeSequenceNumber, e.g. a 32-character hex string without a '/' separating it into two 16-char sections.

Common situations: A 128-bit (32-hex-char) value pasted as a single section instead of being split; uppercase/padded hex from another system exceeding 16 chars; pre-encoded values produced by a different CDC tool with different sectioning rules.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

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

                        value.getClass().getSimpleName()));
    }

    private String encodeIntegralSequenceNumber(BigInteger number) {
        if (number.signum() < 0) {
            throw invalidSequenceNumber("must not be negative");
        }
        if (number.bitLength() > 64) {
            throw invalidSequenceNumber("must not exceed the unsigned 64-bit range");
        }
        return number.toString(16).toUpperCase(Locale.ROOT);
    }

    private void validateSequenceSection(String section) {
        if (section.isEmpty()) {
            throw invalidSequenceNumber("must not contain an empty section");
        }
        if (section.length() > 16) {
            throw invalidSequenceNumber("each section must contain at most 16 characters");
        }
        for (int i = 0; i < section.length(); i++) {
            char character = section.charAt(i);
            boolean isHexDigit =
                    (character >= '0' && character <= '9')
                            || (character >= 'A' && character <= 'F')
                            || (character >= 'a' && character <= 'f');
            if (!isHexDigit) {
                throw invalidSequenceNumber("must contain only hexadecimal characters");
            }
        }
    }

    private SeaTunnelRuntimeException invalidSequenceNumber(String reason) {
        return CommonError.illegalArgument(
                String.format("BigQuery CDC sequence number %s", reason),
                BigQuerySinkOptions.SEQUENCE_NUMBER_COLUMN.key());
    }

View on GitHub (pinned to cf67b549a7)