How to fix Error 2021 on Windows Server 2025 / Windows 11

by

Troubleshooting Guide: Error 2021 — Referenced Entity Modified During DDL Execution

Why This Error Happens

This error occurs when SQL Server detects that an object (table, column, constraint, or index) referenced by a DDL statement was concurrently altered by another session before the original transaction could complete, triggering a metadata version mismatch. It is typically caused by concurrent schema modification operations running against the same object, such as two sessions issuing ALTER TABLE statements simultaneously. In some cases, this can also surface due to stale execution plans or cached metadata that has not been invalidated after a schema change, particularly when OBJECT_ID caching conflicts arise in tempdb-heavy workloads.

Step-by-Step Resolution Guide

Step 1: Identify Concurrent Sessions Modifying the Same Object

  • Open SQL Server Management Studio (SSMS) and connect to the affected instance on Windows Server 2025.
  • Run the following query to check for blocking or concurrent DDL activity:
  SELECT session_id, blocking_session_id, wait_type, wait_time, last_wait_type, command
  FROM sys.dm_exec_requests
  WHERE command LIKE '%ALTER%' OR command LIKE '%CREATE%';
  • Note any session IDs executing schema-altering commands against the same table referenced in the error message.

Step 2: Retry the Operation with Proper Isolation

  • Simply re-running the failed DDL statement often resolves the issue since it is a transient concurrency error.
  • Wrap the DDL statement in a retry loop using TRY...CATCH with a short delay:
  BEGIN TRY
      ALTER TABLE dbo.YourTable ADD NewColumn INT NULL;
  END TRY
  BEGIN CATCH
      IF ERROR_NUMBER() = 2021
          WAITFOR DELAY '00:00:02';
      -- retry logic here
  END CATCH
  • Ensure no scheduled jobs (via SQL Server Agent) are configured to run schema changes at overlapping times.

Step 3: Clear Cached Execution Plans and Metadata

  • If the error persists after retrying, clear the plan cache for the specific database to eliminate stale metadata references:
  DBCC FREEPROCCACHE;
  • Alternatively, target only the affected database using:
  ALTER DATABASE SCOPED CONFIGURATION CLEAR PROCEDURE_CACHE;
  • Restart the SQL Server service via Services.msc (services.msc on Windows Server 2025/Windows 11) if cache clearing does not resolve the mismatch.

Step 4: Review Application-Level Concurrency Controls

  • Check your application code or ORM (such as Entity Framework or Dapper) for any logic that issues concurrent schema migrations, especially during deployment pipelines.
  • Implement an application-level lock (e.g., sp_getapplock) around DDL operations to serialize schema changes:
  EXEC sp_getapplock @Resource = 'SchemaChangeLock', @LockMode = 'Exclusive';
  • Release the lock explicitly after the DDL completes using sp_releaseapplock.

Alternative or Verification Steps

  • Verify the fix by re-running the original DDL script during a low-traffic window and confirming it completes without Error 2021 in the SQL Server Error Log (located at C:\Program Files\Microsoft SQL Server\MSSQL17.MSSQLSERVER\MSSQL\Log\ERRORLOG on Windows Server 2025).
  • As an alternative, schedule all DDL/schema migration scripts through a single controlled deployment tool (e.g., SQL Server Agent job or a CI/CD pipeline step) to prevent overlapping schema changes entirely.