{"record":{"id":"853f4b0f23ccf430","repo":"apache/seatunnel","slug":"bigquery-cdc-sequence-number-must-contain-only-hex","errorCode":null,"errorMessage":"BigQuery CDC sequence number must contain only hexadecimal characters","messagePattern":"BigQuery CDC sequence number must contain only hexadecimal characters","errorType":"exception","errorClass":"SeaTunnelRuntimeException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-bigquery/src/main/java/org/apache/seatunnel/connectors/bigquery/convert/BigQuerySerializer.java","lineNumber":181,"sourceCode":"        }\n        return number.toString(16).toUpperCase(Locale.ROOT);\n    }\n\n    private void validateSequenceSection(String section) {\n        if (section.isEmpty()) {\n            throw invalidSequenceNumber(\"must not contain an empty section\");\n        }\n        if (section.length() > 16) {\n            throw invalidSequenceNumber(\"each section must contain at most 16 characters\");\n        }\n        for (int i = 0; i < section.length(); i++) {\n            char character = section.charAt(i);\n            boolean isHexDigit =\n                    (character >= '0' && character <= '9')\n                            || (character >= 'A' && character <= 'F')\n                            || (character >= 'a' && character <= 'f');\n            if (!isHexDigit) {\n                throw invalidSequenceNumber(\"must contain only hexadecimal characters\");\n            }\n        }\n    }\n\n    private SeaTunnelRuntimeException invalidSequenceNumber(String reason) {\n        return CommonError.illegalArgument(\n                String.format(\"BigQuery CDC sequence number %s\", reason),\n                BigQuerySinkOptions.SEQUENCE_NUMBER_COLUMN.key());\n    }\n}\n","sourceCodeStart":163,"sourceCodeEnd":192,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-bigquery/src/main/java/org/apache/seatunnel/connectors/bigquery/convert/BigQuerySerializer.java#L163-L192","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Convert decimal strings to hex before writing, e.g. Long.toHexString(Long.parseLong(seq)).toUpperCase().","Remove dashes/underscores/whitespace (UUID: uuid.replace(\"-\", \"\")); trim the value upstream.","If the encoding is base36/base62, decode it and re-encode as hexadecimal yourself.","Pre-validate with regex ^[0-9A-Fa-f]{1,16}(/[0-9A-Fa-f]{1,16}){0,3}$ in your pipeline."],"exampleFix":"// before\nString seq = \"550e8400-e29b-41d4\"; // dashes not hex\n// after\nString seq = \"550e8400e29b41d4\"; // dashes removed\n// or convert decimal:\n// seq = Long.toHexString(987654321L).toUpperCase(Locale.ROOT);","handlingStrategy":"validation","validationCode":"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()","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Convert decimal/base36/base62 values to hex before writing.","Strip dashes/underscores/whitespace (UUIDs: replace(\"-\", \"\")).","Trim config-provided strings to avoid accidental whitespace."],"tags":["bigquery","cdc","validation","hex-encoding"],"backgroundTag":"invalid-argument-format","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}