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

by

Troubleshooting Guide: Error 2281 — “Cannot construct DTDs in XQuery”

Why This Error Happens

This error occurs because SQL Server’s XQuery implementation intentionally does not support the construction of Document Type Definitions (DTDs) within XML data type methods, as this is a restriction imposed by the W3C XQuery specification itself. The error typically surfaces when a query, stored procedure, or application-generated XML payload attempts to dynamically build or inject a DOCTYPE declaration using .query(), .modify(), or .value() methods against an xml typed column or variable. It can also appear after migrating legacy XML-processing code from older SQL Server versions (such as 2016 or 2019) to SQL Server 2025, where stricter XQuery parsing rules in the updated engine now catch previously ignored malformed constructs.

Step-by-Step Resolution Guide

Step 1: Identify the Offending Query or Script

  • Check the SQL Server Error Log via SQL Server Management Studio (SSMS) > Management > SQL Server Logs or run EXEC sp_readerrorlog 0, 1, 'Error: 2281'; to locate the exact session and query.
  • Use SELECT * FROM sys.dm_exec_requests WHERE session_id = <SPID>; combined with sys.dm_exec_sql_text() to pull the full text of the failing batch.
  • Look specifically for XML literals containing <!DOCTYPE declarations embedded in FOR XML, OPENXML, or .query('...') calls.

Step 2: Remove or Refactor the DTD Construction Logic

  • Edit the XQuery expression to strip out any <!DOCTYPE ...> declarations from the XML string before it is parsed or inserted into an xml column.
  • If the DTD was being used for entity validation, replace that logic with an XML Schema Collection instead:
  CREATE XML SCHEMA COLLECTION dbo.MySchemaCollection AS N'<xsd:schema>...</xsd:schema>';
  ALTER TABLE dbo.YourTable ALTER COLUMN XmlColumn XML(dbo.MySchemaCollection);
  • Re-test the query in a non-production environment, such as a local instance on Windows 11 or a staging VM on Windows Server 2025, before pushing to production.

Step 3: Patch and Reconfigure SQL Server 2025

  • Confirm your instance is on the latest Cumulative Update by running SELECT @@VERSION; and comparing against the Microsoft Update Catalog for SQL Server 2025.
  • Apply any available CU via Setup.exe or sqlservr.exe -Install silent flags if running in a headless Windows Server 2025 Core deployment.
  • Restart the SQL Server service from services.msc or via PowerShell: Restart-Service -Name 'MSSQLSERVER' -Force.

Step 4: Validate Application-Side XML Generation

  • Audit the client application or ETL pipeline (SSIS, Azure Data Factory, or custom .NET code) that generates the XML payload being sent to SQL Server.
  • Ensure libraries like System.Xml.XmlDocument or XDocument in .NET are not auto-injecting a DOCTYPE node by default — explicitly set DtdProcessing.Prohibit in the XmlReaderSettings.

Alternative or Verification Steps

  • Re-run the original failing query in SSMS or Azure Data Studio; a successful execution with no Error 2281 in the Messages tab confirms the fix.
  • As an alternative, if DTD-based validation is a hard business requirement, pre-process and strip DTDs at the application layer (using an XML parser library) before the data ever reaches SQL Server, since SQL Server’s XQuery engine will never support native DTD construction.