Skip to main content

Search 412 pages — tools, formats, elements, namespaces, directory, comparisons, XPath, datatypes, glossary, parse errors, schema errors, use cases, guides, blog and product.

XSD validation error

No matching global declaration for the validation root

The validator could not find the root element in the schema at all — nearly always a namespace mismatch rather than a genuinely unknown element.

Element 'invoice': No matching global declaration available for the validation root. (line 2)

What it means

Validation starts by finding a global xs:element declaration matching the document's root. If there is none, nothing else can be checked, so this error usually appears alone and everything downstream goes unexamined.

The trap is namespaces. A schema with a targetNamespace declares elements in that namespace, and a document whose root is in no namespace — or in a different one — does not match, however identical the names look. libxml2 makes this visible by printing the root in Clark notation, {namespace}name, so a mismatch is legible in the message itself.

What usually causes it

  • A document missing the default xmlns declaration the schema's targetNamespace requires.
  • A schema with no targetNamespace validating a namespaced document, or the reverse.
  • Validating against the wrong schema — an easy mistake when several are in play.
  • A genuinely different root element: an error envelope where a payload was expected.
  • elementFormDefault="unqualified" misunderstood, so children are unqualified but the root still must not be.

How to fix it

  • Compare the document's root namespace with the schema's targetNamespace; they must be identical strings.
  • If the message shows {some-uri}name, the element is namespaced and the schema is not expecting it there.
  • Check you are validating against the schema you think you are.
  • For multi-namespace vocabularies like UBL, make sure every imported schema is available — an unresolved import looks exactly like a missing declaration.

The same error elsewhere

libxml2 words these plainly. Xerces numbers them, and those cvc- codes are what most people end up searching for.

  • Xerces (Java)

    cvc-elt.1.a: Cannot find the declaration of element 'invoice'.

  • libxml2 (namespaced root)

    Element '{http://example.com/ns}order': No matching global declaration available for the validation root.

  • .NET System.Xml

    The 'invoice' element is not declared.

Before and after

Both documents below are well-formed XML — that is the point. The test suite re-checks them against the real validator on every build: the first is confirmed to produce the exact message above, the second to validate cleanly.

Fails validation
<?xml version="1.0" encoding="UTF-8"?>
<invoice id="A-1">
  <customer>Ada</customer>
  <issued>2026-01-31</issued>
  <state>open</state>
  <line>
    <code>AB-1234</code>
    <qty>2</qty>
  </line>
</invoice>
Validates
<?xml version="1.0" encoding="UTF-8"?>
<order id="A-1">
  <customer>Ada</customer>
  <issued>2026-01-31</issued>
  <state>open</state>
  <line>
    <code>AB-1234</code>
    <qty>2</qty>
  </line>
</order>

The schema both are checked against

order.xsd
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:simpleType name="status">
    <xs:restriction base="xs:string">
      <xs:enumeration value="open"/>
      <xs:enumeration value="closed"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="sku">
    <xs:restriction base="xs:string">
      <xs:pattern value="[A-Z]{2}-\d{4}"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="shortLabel">
    <xs:restriction base="xs:string">
      <xs:minLength value="3"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:element name="order">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="customer" type="xs:string"/>
        <xs:element name="middleName" type="xs:string" minOccurs="0"/>
        <xs:element name="nickname" type="shortLabel" minOccurs="0"/>
        <xs:element name="issued" type="xs:date"/>
        <xs:element name="state" type="status"/>
        <xs:element name="line" minOccurs="1" maxOccurs="2">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="code" type="sku"/>
              <xs:element name="qty" type="xs:positiveInteger"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
      <xs:attribute name="id" type="xs:string" use="required"/>
    </xs:complexType>
  </xs:element>
</xs:schema>
Check your own document← All schema errors

Where this bites most

The terms behind it

Each of these is defined in one sentence and then demonstrated against the parser.

Other schema errors

Get started

Bring order to the XML your team can't afford to ignore.

Create a free account and get a private workspace to search, validate, diff, and monitor your XML feeds, sitemaps, schemas, and vendor integrations.

Get started freeSign in