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

by

Troubleshooting Guide: SQL Server Error 2261

Why This Error Happens

Error 2261 occurs when SQL Server attempts to parse or validate an XML document against an XML Schema Collection (XSD), but the specified element name cannot be located within the referenced complex or simple type definition. This typically results from a mismatch between the XML instance data and the registered schema, often caused by schema versioning drift, a manually edited XML payload, or an incomplete/corrupted XML Schema Collection stored in the database. It can also surface after an application update introduces new XML elements that were never registered via ALTER XML SCHEMA COLLECTION.

Step-by-Step Resolution Guide

Step 1: Identify the Offending XML Schema Collection

  • Run the following query to locate schema collections tied to the affected database:
SELECT name, xml_schema_namespace, schema_id 
FROM sys.xml_schema_collections;
  • Cross-reference the element name mentioned in the error message with the schema’s expected structure.
  • Check SQL Server Error Log (via EXEC xp_readerrorlog; or Event Viewer under Applications and Services Logs > MSSQLSERVER) for the full stack trace and timestamp.

Step 2: Validate the XML Instance Against the Schema

  • Extract the actual XML payload being inserted/updated (often from application logs or a PRINT statement in a repro script).
  • Use SQL Server Management Studio (SSMS) to manually validate:
DECLARE @x XML(YourSchemaCollectionName);
SET @x = '<YourXmlPayload/>';
  • If this throws Error 2261 immediately, you’ve confirmed a mismatch between the instance document and the registered type.

Step 3: Update or Rebuild the XML Schema Collection

  • If the application now sends new elements, update the schema using:
ALTER XML SCHEMA COLLECTION YourSchemaCollectionName 
ADD '<xsd:schema>...updated definition...</xsd:schema>';
  • If the schema collection itself appears corrupted, drop and recreate it entirely (ensure no dependent columns/tables reference it first):
DROP XML SCHEMA COLLECTION YourSchemaCollectionName;
CREATE XML SCHEMA COLLECTION YourSchemaCollectionName AS 
'<xsd:schema>...full correct definition...</xsd:schema>';
  • On Windows Server 2025, ensure the SQL Server service account has read access to any external .xsd files if you’re loading the schema from disk (typically under C:\Program Files\Microsoft SQL Server\MSSQL17.MSSQLSERVER\MSSQL\Schemas\).

Step 4: Restart the SQL Server Service and Clear Plan Cache

  • Restart via PowerShell to ensure schema changes are fully reloaded:
Restart-Service -Name 'MSSQLSERVER' -Force
  • Clear cached execution plans that may reference the old schema definition:
DBCC FREEPROCCACHE;

Alternative or Verification Steps

  • Re-run the original INSERT/UPDATE statement or application transaction that triggered Error 2261 and confirm it completes without exception.
  • As a fallback, temporarily relax validation by casting the column to untyped XML (XML without a schema reference) to confirm the schema itself—not the data—is the root cause, then re-apply typing once the schema is corrected.