apache/seatunnel · error · SeaTunnelRuntimeException

BigQuery CDC sequence number must contain only hexadecimal…

Error message

BigQuery CDC sequence number must contain only hexadecimal characters

What it means

Sequence number sections must consist solely of hexadecimal characters (0-9, A-F, a-f); validateSequenceSection rejects any other character because the section is interpreted as a hex-encoded unsigned value.

Solutions

1. Convert decimal strings to hex before writing, e.g. Long.toHexString(Long.parseLong(seq)).toUpperCase().
2. Remove dashes/underscores/whitespace (UUID: uuid.replace("-", "")); trim the value upstream.
3. If the encoding is base36/base62, decode it and re-encode as hexadecimal yourself.
4. Pre-validate with regex ^[0-9A-Fa-f]{1,16}(/[0-9A-Fa-f]{1,16}){0,3}$ in your pipeline.

Example fix

// before
String seq = "550e8400-e29b-41d4"; // dashes not hex
// after
String seq = "550e8400e29b41d4"; // dashes removed
// or convert decimal:
// seq = Long.toHexString(987654321L).toUpperCase(Locale.ROOT);

boolean isHex = seq.matches("^[0-9A-Fa-f]+(/[0-9A-Fa-f]+)*$"); if (!isHex) { throw new IllegalArgumentException("sequence number must be hexadecimal: " + seq); } // decimal -> hex: Long.toHexString(Long.parseLong(seq)).toUpperCase()

When it happens

Trigger: A section of the sequence_number_column string contains a non-hex character (e.g. 'g'-'z', '-', '_', '.', or decimal separators) when validateSequenceSection iterates its chars.

Common situations: Passing decimal strings with separators ("1,000"), signed numbers ("-5"), UUIDs with dashes, or base62/base36 encodings from another system; accidental whitespace from config trimming failures.

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

• BigQuery CDC sequence number each section must contain at…
• COMMON-06
• Incremental snapshot for tables requires primary key, but…
• Streaming mode requires a Primary Key in the schema of…
• A deserialization failure event arrived

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

Appendix: source

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

        }
        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)