apache/seatunnel · warning

Tables were locked explicitly, but to get a consistent snaps

Error message

Tables were locked explicitly, but to get a consistent snapshot we cannot release the locks until we've read all tables.

What it means

When the snapshot could not obtain a global read lock (FLUSH TABLES WITH READ LOCK) and instead locked tables explicitly (LOCK TABLES), releasing locks via UNLOCK TABLES would implicitly commit the active transaction that holds the consistent-snapshot read view. Debezium therefore deliberately skips unlocking and warns that locks are held until all tables are read.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/io/debezium/connector/mysql/MySqlSnapshotChangeEventSource.java:265

    @Override
    protected void releaseSchemaSnapshotLocks(
            RelationalSnapshotContext<MySqlPartition, MySqlOffsetContext> snapshotContext)
            throws SQLException {
        if (connectorConfig.getSnapshotLockingMode().usesMinimalLocking()) {
            if (isGloballyLocked()) {
                globalUnlock();
            }
            if (isTablesLocked()) {
                // We could not acquire a global read lock and instead had to obtain individual
                // table-level read locks
                // using 'FLUSH TABLE <tableName> WITH READ LOCK'. However, if we were to do this,
                // the 'UNLOCK TABLES'
                // would implicitly commit our active transaction, and this would break our
                // consistent snapshot logic.
                // Therefore, we cannot unlock the tables here!
                // https://dev.mysql.com/doc/refman/5.7/en/flush.html
                LOGGER.warn(
                        "Tables were locked explicitly, but to get a consistent snapshot we cannot release the locks until we've read all tables.");
            }
        }
    }

    @Override
    protected void releaseDataSnapshotLocks(
            RelationalSnapshotContext<MySqlPartition, MySqlOffsetContext> snapshotContext)
            throws Exception {
        if (isGloballyLocked()) {
            globalUnlock();
        }
        if (isTablesLocked()) {
            tableUnlock();
            if (!delayedSchemaSnapshotTables.isEmpty()) {
                schemaEvents.clear();
                createSchemaEventsForTables(snapshotContext, delayedSchemaSnapshotTables, false);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Grant the connector user privileges to take a global read lock (RELOAD + FLUSH_TABLES) so the explicit-lock fallback is not used
2. Use snapshot.mode with a consistent snapshot mechanism (e.g. schema-only or when_needed with GTID) orDebezium's incremental snapshot to avoid long locks
3. Ensure the snapshot completes promptly — keep the window between lock and unlock small; monitor for stuck snapshots
4. If the warning appears after a completed snapshot, verify the history topic recorded all tables; run a new snapshot if the history is incomplete

Example fix

// before
connectorConfig.snapshotLockingMode(SnapshotLockingMode.MINIMAL)
// after (use extended locking so a consistent global lock is taken, avoiding the explicit-lock fallback)
connectorConfig.snapshotLockingMode(SnapshotLockingMode.EXTENDED)

// Ensure the connector user can take a global read lock so the explicit-lock fallback is avoided:
// SHOW GRANTS FOR 'cdc_user'@'%';
// -- must include RELOAD (and FLUSH_TABLES on MySQL 8) for FLUSH TABLES WITH READ LOCK

When it happens

Trigger: releaseSchemaSnapshotLocks runs and lockTables was true — i.e. the global read lock failed so the source fell back to per-table explicit locks, and UNLOCK TABLES was suppressed to preserve snapshot consistency.

Common situations: MySQL 8.0.32+/managed clouds where FLUSH TABLES WITH READ LOCK requires privileges the CDC user lacks; large schemas where the explicit-lock fallback is exercised; operators seeing locks held long on big snapshots and wondering why they aren't released.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• User does not have the 'LOCK TABLES' privilege required to o
• Cannot read the binlog filename and position via '<showMaste
• Interrupted while emitting initial DROP TABLE events
• User does not have the 'LOCK TABLES' privilege required to o
• Read snapshot for split ${split} fail

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