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

by

Why This Error Happens

Error 2321 occurs when SQL Server’s XML parser processes an XSD schema (typically during a CREATE XML SCHEMA COLLECTION or ALTER XML SCHEMA COLLECTION statement) that violates W3C XML Schema ordering rules. Specifically, the schema definition contains facet elements (such as <xs:minLength>, <xs:pattern>, or <xs:enumeration>) placed after an <xs:attribute> declaration inside a <xs:restriction> block, when the correct order requires all facets to precede any attribute declarations. This is almost always caused by a manually edited or auto-generated XSD file that wasn’t validated against the schema’s content model before being imported into SQL Server 2025.

Step-by-Step Resolution Guide

Step 1: Isolate the Offending XSD File

  • Locate the exact .xsd file referenced in the CREATE XML SCHEMA COLLECTION statement that triggered the error.
  • Open the file in a structured XML editor (Visual Studio 2022/2025 or VS Code with the XML extension) rather than a plain text editor to get schema-aware validation.
  • Note the location path reported in the error message (e.g., #/complexType[2]/restriction/attribute[1]) — this tells you exactly which node is malformed.

Step 2: Correct the Facet/Attribute Ordering

  • Within the <xs:complexType> or <xs:simpleType> block identified, move all facet elements (<xs:minLength>, <xs:maxLength>, <xs:pattern>, <xs:enumeration>, <xs:totalDigits>, etc.) so they appear immediately after the <xs:restriction base="..."> opening tag.
  • Ensure <xs:attribute> declarations appear strictly after all facet elements, per the XSD content model: restriction -> (facets)* -> (attribute | attributeGroup)*.
  • Save the corrected file as UTF-8 without BOM to avoid encoding issues on import.

Step 3: Re-import the Schema Collection in SQL Server

  • Drop the broken schema collection if a partial version exists:
DROP XML SCHEMA COLLECTION dbo.MySchemaCollection;
  • Re-run the creation statement pointing to the corrected file:
CREATE XML SCHEMA COLLECTION dbo.MySchemaCollection AS N'
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   -- corrected schema content here
</xs:schema>';
  • Check sys.xml_schema_collections to confirm the object registered successfully.

Step 4: Validate with an External XSD Validator

  • Before re-importing, run the file through xmllint --schema (available via Windows Subsystem for Linux on Windows 11/Server 2025) or the .NET XmlSchemaSet class to catch ordering errors pre-emptively.
  • Example command: xmllint --noout --schema myschema.xsd sample.xml

Alternative or Verification Steps

  • Verify the fix by querying sys.xml_schema_collections and sys.xml_schema_components to confirm the schema loaded without error and that attribute/facet nodes appear in the expected sequence.
  • If the schema is auto-generated (e.g., exported from an ORM or third-party tool), regenerate it using an updated version of that tool, as older generators are known to emit non-compliant facet/attribute ordering that newer XSD 1.1-aware tools correct automatically.