MySQL-CDC diagnostic: required binlog sequence

Error message

MySQL-CDC diagnostic: required binlog sequence {}{} is within available range {}{}..{}{} but missing; possible manual binlog deletion, binlog.index corruption, or connecting to a different MySQL instance intermittently

What it means

Diagnostic WARN emitted when the required binlog sequence falls numerically BETWEEN the smallest and largest available binlog files, yet the exact required file is absent from SHOW BINARY LOGS. The server's file list is 'holey': the file was deleted selectively, the binlog index is inconsistent, or the queries hit different servers at different times.

Solutions

Check whether files were deleted manually (PURGE BINARY LOGS, rm) and repair/validate the binlog.index file.
Pin the CDC connection to a single MySQL instance (bypass proxies/LBs) so SHOW BINARY LOGS is answered consistently.
If the gap file is unrecoverable, restart the CDC job from a fresh snapshot.
Restore the missing binlog file from backups if resume-from-offset is required.

Example fix

// before: deleting binlogs directly on disk
rm /var/lib/mysql/mysql-bin.000120*
// after: use supported purge of all files up to a point
mysql> PURGE BINARY LOGS TO 'mysql-bin.000151';

Defensive patterns

Strategy: validation

Validate before calling

SHOW BINARY LOGS; -- confirm no gaps: every file between min and max must be listed

Prevention

Never rm binlog files directly; use PURGE BINARY LOGS.
If binlog.index is suspected corrupt, stop the server and repair before resuming CDC.
Route CDC traffic to one instance; inconsistent SHOW BINARY LOGS across nodes causes 'hole' symptoms.
Restore missing files from backup to resume from the exact offset.

When it happens

Trigger: logBinlogRangeAnalysis (via logBinlogNotAvailableDiagnostics): min <= required.number <= max but the required filename is not in the enumerated list — e.g. available {000100..000150} minus 000120, required 000120.

Common situations: Manual PURGE BINARY LOGS TO a later file or manual rm of individual binlog files (corrupting binlog.index); a load balancer flapping between primary and replica with divergent binlog sets; RESET MASTER partially replayed across nodes.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/mysql/source/reader/fetch/MySqlSourceFetchTaskContext.java:642

            return;
        }

        if (required.number < min) {
            LOG.warn(
                    "MySQL-CDC diagnostic: required binlog sequence {}{} is older than the earliest available {}{}; likely purged/expired binlog on server",
                    required.prefix,
                    required.number,
                    required.prefix,
                    min);
        } else if (required.number > max) {
            LOG.warn(
                    "MySQL-CDC diagnostic: required binlog sequence {}{} is newer than the latest available {}{}; possible connection to an out-of-date replica, proxy routing to different instance, or RESET MASTER",
                    required.prefix,
                    required.number,
                    required.prefix,
                    max);
        } else {
            LOG.warn(
                    "MySQL-CDC diagnostic: required binlog sequence {}{} is within available range {}{}..{}{} but missing; possible manual binlog deletion, binlog.index corruption, or connecting to a different MySQL instance intermittently",
                    required.prefix,
                    required.number,
                    required.prefix,
                    min,
                    required.prefix,
                    max);
        }
    }

    private static String summarizeBinlogFiles(List<String> files) {
        if (files == null || files.isEmpty()) {
            return "available binlog files: (empty)";
        }
        int total = files.size();
        int headCount = Math.min(BINLOG_FILE_SAMPLE_SIZE, total);
        int tailCount = Math.min(BINLOG_FILE_SAMPLE_SIZE, Math.max(0, total - headCount));

View on GitHub (pinned to cf67b549a7)