Environment

• YugabyteDB (Versions lower than 2024.x) 

Issue

Scheduled or manual backups fail because a table is stuck in a "DDL verification" state. The process is blocked because a specific table is stuck in a "DDL verification" state.

Symptoms

During a schedule backup attempt, the following log message appears in the YB-Controller logs:

Table <Table_ID> is undergoing DDL verification, retry later

The corresponding YB-Master logs shows:

Operation failed. Try again (yb/master/ysql_ddl_handler.cc:380): Table is undergoing DDL transaction verification: <table_name> [id=<Table_ID>]

Cause

A previous DDL operation (schema change) triggered the table to enter a DDL verification state, but the background process failed to clear this state. When the backup process attempts to run, it detects this pending state and aborts to prevent data inconsistency. This is often exacerbated if the cluster is using the preview G-Flag ysql_ddl_rollback_enabled without the necessary fixes present in newer versions.

Note: Preview flags must be explicitly acknowledged before modification. Flags marked as “Preview” cannot be changed unless they are included in the allowed list. By adding them to this list, you accept the associated risks. Refer to the official CSV-formatted list of allowed preview flags: Preview Flags CSV

Resolution

Immediate (Manual) Resolution

1. Identify the Stuck Table:
   Find the table ID (e.g., 00004b0000003000800000000000da2d) in the logs.

2. Trigger DDL Finalization:
   This action forces YugabyteDB to finalize the DDL verification and clear the state.

   -- Step A: Add a dummy column (This first attempt may fail, which is expected)
   ALTER TABLE <affected_table_name> ADD COLUMN dummy_col INT;
   
   -- Step B: Retry adding the dummy column (This should succeed and clear the stuck state)
   ALTER TABLE <affected_table_name> ADD COLUMN dummy_col INT;
   
   -- Step C: Clean up by removing the dummy column
   ALTER TABLE <affected_table_name> DROP COLUMN dummy_col;

3. Retry Backup:
   Backups should succeed once the stale verification state is removed.

4. If above does not work then you need to manually Delete Table from DocDB:
   Remove the stale table entry from the DocDB layer.

   ./bin/yb-admin -master_addresses <master-addresses> delete_table_by_id <uuid>

Warning: Manual deletion carries risk. Contact Yugabyte Support for guidance if unsure.

Permanent Resolution

• Upgrade YugabyteDB:
  Move to the latest stable release in the 2024.x or 2025.x series for improved DDL atomicity and preview G-Flag handling.
  Note: Upgrading alone does NOT automatically unblock backups during DDL verification. Backups during DDL verification remain blocked by default.
• To enable backups during DDL verification, set the runtime config yb.backup.enable_backups_during_ddl to true in YBA (Early Access feature).
  Always consult the official documentation and release notes to confirm the support status of any preview flag before using it in production.

See Also: https://support.yugabyte.com/hc/en-us/articles/41977905074061-Understanding-error-Table-Table-ID-is-undergoing-DDL-verification

Reference: SUPPORT-524