apache/seatunnel · error · IllegalStateException

Could not find existing binlog information while attempting

Error message

Could not find existing binlog information while attempting schema only recovery snapshot

What it means

In schema-only recovery snapshot mode, SnapshotReader.readBinlogPosition expects the stored offsets to contain a previously recorded binlog filename from an earlier run. If source.binlogFilename() is null or empty, an IllegalStateException is thrown because recovery cannot resume the stream without a known binlog position.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/io/debezium/connector/mysql/legacy/SnapshotReader.java:1015

    /** Whether DDL for the given table should be recorded. */
    private boolean shouldRecordTableSchema(MySqlSchema schema, Filters filters, TableId id) {
        // some tables are always ignored, also if we're recording the schema of non-captured tables
        if (filters.ignoredTableFilter().test(id)) {
            return false;
        }

        return filters.tableFilter().test(id) || !schema.isStoreOnlyCapturedTablesDdl();
    }

    protected void readBinlogPosition(
            int step, SourceInfo source, JdbcConnection mysql, AtomicReference<String> sql)
            throws SQLException {
        if (context.isSchemaOnlyRecoverySnapshot()) {
            // We are in schema only recovery mode, use the existing binlog position
            if (Strings.isNullOrEmpty(source.binlogFilename())) {
                // would like to also verify binlog position exists, but it defaults to 0 which is
                // technically valid
                throw new IllegalStateException(
                        "Could not find existing binlog information while attempting schema only recovery snapshot");
            }
            source.startSnapshot();
        } else {
            logger.info("Step {}: read binlog position of MySQL primary server", step);
            String showMasterStmt = ((MySqlConnection) mysql).binaryLogStatusStatement();
            sql.set(showMasterStmt);
            mysql.query(
                    sql.get(),
                    rs -> {
                        if (rs.next()) {
                            String binlogFilename = rs.getString(1);
                            long binlogPosition = rs.getLong(2);
                            source.setBinlogStartPoint(binlogFilename, binlogPosition);
                            if (rs.getMetaData().getColumnCount() > 4) {
                                // This column exists only in MySQL 5.6.5 or later ...
                                String gtidSet =
                                        rs.getString(

View on GitHub (pinned to cf67b549a7)

Solutions

1. Run an initial snapshot first (snapshot.mode=initial/when_needed) so a binlog position is persisted in offsets.
2. Restore the offset storage (Kafka offsets topic / local offsets file) from backup.
3. Use snapshot.mode=schema_only instead of schema_only_recovery if no prior state should exist.
4. Verify binlogFilename offset key exists in stored offsets before using recovery mode.

Example fix

// before
'snapshot.mode': 'schema_only_recovery'  // no prior offsets exist
// after
'snapshot.mode': 'initial'  // run once to establish offsets, then switch

// Check offsets contain a binlog filename before recovery mode
String binlogFile = (String) offsets.get("binlog_file");
if (binlogFile == null || binlogFile.isEmpty()) {
    throw new IllegalStateException("schema_only_recovery requires existing offsets with binlog_file");
}

try { recover(); } catch (IllegalStateException e) { if (e.getMessage().contains("Could not find existing binlog")) { /* fall back to initial snapshot */ } throw e; }

When it happens

Trigger: Running with snapshot.mode=schema_only_recovery when offsets are missing, corrupted, or the connector was never run before (no prior binlog position was stored), so binlogFilename() returns empty.

Common situations: Starting a fresh connector directly with schema_only_recovery; deleted/lost offset storage (Kafka topic or file dropped); offsets wiped after reconfiguration of offset.topic.name.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Read snapshot for split %s fail
• Invalid state: currentSplitId is null when emitting records.
• Cannot fetch from another split - no split remaining.
• Read snapshot for split %s fail
• Snapshotting of table failed

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