apache/seatunnel · error

Connector requires binlog file '{}', but it is not available

Error message

Connector requires binlog file '{}', but it is not available on the connected MySQL server. {}

What it means

When restoring a MySQL CDC reader from a saved offset, checkBinlogFilename() (called from isBinlogAvailable) compares the binlog filename required by the connector's offset against the list returned by SHOW BINARY LOGS. If the required file is no longer on the server, the reader cannot resume from that offset; this warning plus diagnostics are logged and the fetch task aborts.

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:349

        return checkBinlogFilename(offset);
    }

    private boolean checkBinlogFilename(MySqlOffsetContext offset) {
        String binlogFilename = offset.getSourceInfo().getString(BINLOG_FILENAME_OFFSET_KEY);
        if (binlogFilename == null) {
            return true; // start at current position
        }
        if (binlogFilename.equals("")) {
            return true; // start at beginning
        }

        // Accumulate the available binlog filenames ...
        List<String> logNames = connection.availableBinlogFiles();

        // And compare with the one we're supposed to use ...
        boolean found = logNames.stream().anyMatch(binlogFilename::equals);
        if (!found) {
            LOG.warn(
                    "Connector requires binlog file '{}', but it is not available on the connected MySQL server. {}",
                    binlogFilename,
                    summarizeBinlogFiles(logNames));
            logBinlogNotAvailableDiagnostics(binlogFilename, logNames, offset);
        } else {
            LOG.info("MySQL has the binlog file '{}' required by the connector", binlogFilename);
        }
        return found;
    }

    private boolean checkGtidSet(MySqlOffsetContext offset) {
        String gtidStr = offset.gtidSet();

        if (gtidStr.trim().isEmpty()) {
            return true; // start at beginning ...
        }

        String availableGtidStr = connection.knownGtidSet();

View on GitHub (pinned to cf67b549a7)

Solutions

1. Restart the CDC job with a fresh/earlier snapshot (drop the saved state) so a new consistent snapshot is taken.
2. Increase binlog retention: SET PERSIST binlog_expire_logs_seconds = <larger>; and ensure enough disk space before long job stoppages.
3. Restore the required binlog file from backup into the server's binlog directory if available.
4. Point the job at the same server (not a replica without the binlog) or use GTID-based offsets instead of filenames.

Example fix

-- before (server)
binlog_expire_logs_seconds = 86400  -- 1 day
-- after
SET PERSIST binlog_expire_logs_seconds = 604800; -- 7 days

-- Before resuming a stopped job, verify the offset's binlog still exists:
SHOW BINARY LOGS;
-- Compare with the checkpoint's binlog filename.

When it happens

Trigger: checkBinlogFilename(): logNames.stream().anyMatch(binlogFilename::equals) is false — the offset's binlog file was purged by MySQL retention (expire_logs_days/binlog_expire_logs_seconds) or RESET BINARY LOGS ran, so the filename is absent from connection.availableBinlogFiles().

Common situations: Job checkpoint is older than the binlog retention window (server purged old binlogs while the job was stopped); failover to a replica with different binlog files; MySQL restarted with binlog files cleaned; resuming a long-idle job.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Some of the GTIDs needed to replicate have been already purg
• MySQL-CDC diagnostic: variable {}={}
• MySQL-CDC diagnostic: required binlog sequence {}{} is older
• Unexpected error while connecting to MySQL and looking at gt
• Unexpected error while connecting to MySQL and looking for b

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