Skip to content

Error codes ​

Every error code, grouped by prefix, with the condition that raises it. Errors and locations covers catching errors and reading their locations.

The codes of the XML packages are the values of ErrorCode from @exemplarjs/xml. Each member's value is its own name, so error.code === 'WF_TAG' and error.code === ErrorCode.WF_TAG are equivalent.

How each family is reported ​

Each code is reported at one of three severities: fatal error, recoverable error or warning. Errors and locations describes them.

FamilyCodesKind
Not well-formedWF_*Fatal error
NamespacesNS_*Fatal error
EncodingENCODING_*Fatal error, except the two marked below
LimitsLIMIT_*Fatal error
Access and resolutionDOCTYPE_DISALLOWED, ACCESS_REFUSED, RESOLVER_FAILED, RESOLVER_MISSINGFatal error, except ACCESS_REFUSED, which is recoverable
DTD declarationsDTD_DUPLICATE_*Warning
ValidityVC_*Recoverable error
xml:idXMLID_*Warning
CatalogsCATALOG_*Fatal error
XIncludeXINCLUDE_*Fatal error
Canonical XMLC14N_*canonicalize throws an XMLError
WriterWRITE_*The write throws a WriterError
XPathXPST*, XPTY*, XPDY*, FO* and othersAn XPathException is thrown

A fatal error is passed to the error handler's fatalError and then thrown as an XMLError. A recoverable error is passed to the handler's error, or thrown when the handler has no error function, which is the default. A warning is passed to warning and is never thrown.

An error's message combines its code, its description and its location, as in WF_END_TAG_MISMATCH: Expected </title> (file:///data/books.xml 3:30).

Not well-formed: the document ​

CodeMeaning
WF_EMPTY_DOCUMENTThe document has no root element
WF_XML_DECLARATIONThe XML declaration is malformed
WF_XML_DECLARATION_MISPLACEDThe XML declaration is not at the start of the document
WF_DOCTYPEThe DOCTYPE is malformed
WF_DOCTYPE_MISPLACEDA DOCTYPE comes after the root element, or there is a second DOCTYPE
WF_CONTENT_OUTSIDE_ROOTText, CDATA or a reference comes before or after the root element
WF_SECOND_ROOTThere is a second root element
WF_UNEXPECTED_ENDThe input ends inside an unterminated construct, such as a tag or a comment
WF_INVALID_CHARACTERA character that the document's XML version does not permit, such as a control character
WF_LINE_END_IN_DECLARATIONAn XML 1.1 line-end character (U+0085 or U+2028) inside an XML or text declaration

Not well-formed: markup ​

CodeMeaning
WF_NAMEA name is missing where one is expected, such as after <
WF_MARKUP<! does not begin a comment, CDATA section or DOCTYPE
WF_TAGA start or end tag is malformed
WF_END_TAG_MISMATCHAn end tag does not match the open element, or has no start tag
WF_UNCLOSED_ELEMENTAn element is still open at the end of the document
WF_ATTRIBUTEAn attribute is malformed: no =, or a value without quotes
WF_DUPLICATE_ATTRIBUTEAn attribute appears twice in one start tag
WF_LT_IN_ATTRIBUTE< appears in an attribute value, literally or through an entity's replacement text
WF_COMMENT-- appears inside a comment
WF_PIA processing instruction is malformed
WF_PI_TARGET_XMLA processing instruction's target is xml in a different letter case, such as XML
WF_CDATA_END_IN_TEXT]]> appears in text outside a CDATA section

Not well-formed: references and entities ​

CodeMeaning
WF_REFERENCEA reference is malformed, such as & without a name or ;
WF_CHARACTER_REFERENCEA character reference is malformed, or names a character that is not allowed
WF_UNDECLARED_ENTITYA reference names an entity that is not declared
WF_RECURSIVE_ENTITYAn entity refers to itself, directly or through others
WF_UNPARSED_ENTITYA reference names an unparsed entity, one declared with NDATA
WF_EXTERNAL_ENTITY_IN_ATTRIBUTEAn attribute value refers to an external entity
WF_ENTITY_CONTENTAn entity's replacement text is not balanced: it closes an element it did not open, or leaves one open
WF_ENTITY_VERSIONAn XML 1.1 external entity is used in an XML 1.0 document

Two related codes are recoverable errors:

CodeMeaning
VC_ENTITY_DECLAREDA reference names an undeclared entity, in a document whose DTD may declare it elsewhere
UNREAD_ENTITY_IN_ATTRIBUTEAn attribute value refers to an entity that may be declared in a part of the DTD that was not read

Not well-formed: the DTD ​

CodeMeaning
WF_DECLARATIONA declaration in the DTD is malformed
WF_PE_IN_INTERNAL_SUBSETA parameter-entity reference appears inside a declaration in the internal DTD subset
WF_PE_BETWEEN_DECLARATIONSA parameter entity referenced between declarations does not contain complete declarations
WF_CONDITIONAL_SECTIONA conditional section is malformed, or appears in the internal DTD subset
WF_TEXT_DECLARATIONThe text declaration at the start of an external entity is malformed

See DTDs and entities.

Namespaces ​

CodeMeaning
NS_QNAMEA name has more than one colon, or a colon at either end
NS_COLONA colon appears in a name that may not have one, such as an entity name
NS_UNBOUND_PREFIXA prefix has no namespace declaration in scope
NS_RESERVEDThe reserved xml or xmlns prefixes or namespaces are misused
NS_UNDECLARED_PREFIXxmlns:p="" in an XML 1.0 document, which cannot undeclare a prefix
NS_DUPLICATE_ATTRIBUTETwo attributes have the same namespace URI and local name

These are raised only with namespaceAware on, the default. See Namespaces.

Encoding ​

CodeMeaningKind
ENCODING_UNSUPPORTEDNo decoder is registered for the document's encodingFatal error
ENCODING_INVALID_BYTESThe document contains a byte sequence that is invalid in its encodingFatal error
ENCODING_MISMATCHThe encoding named in the XML declaration contradicts the byte-order mark or the initial bytesFatal error
ENCODING_UNDECLAREDThe document is in UTF-16 or another encoding that must be declared, and has neither a byte-order mark nor a declarationFatal error
ENCODING_UTF16_WITHOUT_BOMThe document is declared as UTF-16 but has no byte-order markRecoverable error
ENCODING_CONFLICTThe encoding supplied with the source differs from the declared encoding and overrides itWarning

See Encodings.

Limits ​

CodeMeaning
LIMIT_ENTITY_EXPANSIONSMore entity expansions than limits.entityExpansions
LIMIT_TOTAL_ENTITY_SIZEEntity expansions produce more characters in total than limits.totalEntitySize
LIMIT_GENERAL_ENTITY_SIZEOne entity is longer than limits.generalEntitySize
LIMIT_PARAMETER_ENTITY_SIZEOne parameter entity is longer than limits.parameterEntitySize
LIMIT_ENTITY_REPLACEMENTMore events are produced inside entities than limits.entityReferenceNodes
LIMIT_ELEMENT_DEPTHElements are nested deeper than limits.elementDepth
LIMIT_ATTRIBUTESAn element has more attributes than limits.attributesPerElement
LIMIT_NAME_LENGTHA name is longer than limits.nameLength

See Limits for the defaults and Untrusted input.

Access and resolution ​

CodeMeaningKind
DOCTYPE_DISALLOWEDThe document has a DOCTYPE and disallowDoctype is onFatal error
ACCESS_REFUSEDAn external resource that a resolver or catalog could supply has a protocol not listed in accessExternalDTD or accessExternalEntitiesRecoverable error
RESOLVER_FAILEDReserved for custom resolvers: thrown in a ResolutionError when the resolver cannot supply the requested resourceFatal error
RESOLVER_MISSINGThe access lists permit an external resource, but the factory has no resolver and no catalogFatal error

See Resolvers and access.

DTD declarations ​

CodeMeaningKind
DTD_DUPLICATE_ENTITYA DTD declares an entity a second time; the first declaration is usedWarning
DTD_DUPLICATE_ATTRIBUTEA DTD declares an attribute of an element a second time; the first declaration is usedWarning

See DTDs and entities.

Validity ​

Reported only when a validator is set. Each is a recoverable error. See Validating against a DTD.

The document ​

CodeMeaning
VC_ROOT_ELEMENTThere is no DOCTYPE, or the root element's name differs from the name the DOCTYPE declares
VC_ELEMENT_VALIDAn element does not match its declared content, or is not declared
VC_ATTRIBUTE_TYPEAn attribute is not declared for its element, or its value does not conform to its declared type
VC_REQUIRED_ATTRIBUTEA required attribute is missing
VC_FIXED_DEFAULTAn attribute declared with a fixed value is given a different one
VC_ENUMERATIONAn attribute's value is not one of its enumerated values
VC_IDAn ID value is used more than once in the document
VC_IDREFAn IDREF value matches no ID in the document
VC_ENTITY_NAMEAn attribute of type ENTITY or ENTITIES does not name a declared unparsed entity
VC_NAME_TOKENAn attribute of type NMTOKEN or NMTOKENS has a value that is not a valid name token
VC_NOTATION_ATTRIBUTESA NOTATION attribute's value or declaration names an undeclared notation
VC_NAMESPACE_COLONAn ID, IDREF, ENTITY or NOTATION value contains a colon
VC_STANDALONEA document that declares standalone="yes" depends on external declarations

The DTD ​

CodeMeaning
VC_UNIQUE_ELEMENT_TYPEAn element is declared more than once
VC_NO_DUPLICATE_TYPESAn element name appears twice in one mixed-content declaration
VC_PE_NESTINGA declaration or group starts in one parameter entity and ends in another
VC_ONE_IDAn element has more than one ID attribute declared
VC_ID_DEFAULTAn ID attribute is declared with a default value
VC_ONE_NOTATIONAn element has more than one NOTATION attribute declared
VC_NOTATION_EMPTYA NOTATION attribute is declared for an element declared empty
VC_DUPLICATE_TOKENSA token appears twice in one attribute's enumeration
VC_DEFAULT_SYNTAXAn attribute's declared default does not conform to its type
VC_NOTATION_DECLAREDAn unparsed entity names a notation that is not declared
VC_UNIQUE_NOTATIONA notation is declared more than once

xml:id ​

Reported without a validator. Each is a warning. See DTDs and entities.

CodeMeaning
XMLID_NAMEAn xml:id value is not an NCName, a valid name without a colon
XMLID_TYPEThe DTD declares xml:id with a type other than ID
XMLID_DUPLICATEAn ID value is used twice, and at least one of the two is an xml:id

Normalization ​

CodeMeaningKind
NOT_FULLY_NORMALIZEDThe text of an XML 1.1 document is not fully normalized, with checkNormalization onWarning

Catalogs ​

CodeMeaning
CATALOG_NO_MATCHNo catalog entry matches a reference, and the catalog's resolution setting is 'strict'
CATALOG_UNREADABLEA catalog file listed in files cannot be found or read
CATALOG_CIRCULARA catalog file references itself, directly or through other catalogs

See Catalogs.

XInclude ​

CodeMeaning
XINCLUDE_RESOURCEA resource to include cannot be read, and there is no fallback
XINCLUDE_POINTERAn xpointer is malformed or identifies nothing, and there is no fallback
XINCLUDE_LOOPA document includes itself, directly or through others
XINCLUDE_ATTRIBUTEAn attribute of xi:include is missing, not allowed or malformed
XINCLUDE_STRUCTURExi:include or xi:fallback appears where it is not allowed
XINCLUDE_ROOTThe root element is replaced by content other than exactly one element
XINCLUDE_TEXTIncluded text contains a character that XML does not permit
XINCLUDE_DECLARATIONTwo included documents declare an unparsed entity or notation of the same name differently

See XInclude.

Canonical XML ​

canonicalize throws an XMLError with one of these codes.

CodeMeaning
C14N_UNREADThe document's DTD or an entity was not read, so the result would be incomplete
C14N_RELATIVE_NAMESPACEThe document has a relative namespace URI
C14N_VERSIONThe document is XML 1.1

See Canonical XML.

Writer ​

A write method throws a WriterError with one of these codes. Most are raised only while the writer's checkWellFormedness is on, the default. WRITE_ENCODING is raised regardless, as are WRITE_STATE and WRITE_UNBOUND_PREFIX for a write that cannot be performed at all, such as an end tag with no open element. See Writing XML.

CodeMeaning
WRITE_NAMEA name is not valid, or a namespace declaration or entity reference is not allowed there
WRITE_CHARACTERA character that the XML version does not permit
WRITE_COMMENTA comment contains -- or ends with -
WRITE_PIA processing instruction has a target that is not allowed, or data that contains ?>
WRITE_CDATAA CDATA section contains ]]>
WRITE_STATEThe write is not valid in the writer's current state, such as an XML declaration after content or an end tag whose name differs from the open element
WRITE_DUPLICATE_ATTRIBUTEAn attribute, or a prefix's declaration, is written twice on one element
WRITE_UNBOUND_PREFIXA name is in a namespace with no bound prefix, or in no namespace while a default namespace is in scope and xmlns="" has not been written
WRITE_ENCODINGA character that the output encoding cannot represent, in a name or comment; or a declared encoding that differs from the output encoding

XPath ​

XPath errors are thrown as an XPathException, whose code is one of the standard XPath codes. exemplar adds no codes of its own. The prefix of a code identifies the kind of error:

CodesKindRaised
XPST…Static errorAt compilation
XPTY…Type errorAt compilation or evaluation
XPDY…Dynamic errorAt evaluation
FO…Function errorAt evaluation
SE…Serialization errorWhen serialize runs
XQ…Shared with XQueryAt compilation or evaluation

The most common codes:

CodeMeaning
XPST0003The expression has a syntax error
XPST0008A variable is not declared
XPST0017No function has that name and arity
XPTY0004A value has the wrong type
XPDY0002The expression needs a context item and has none
FORG0001A value cannot be cast to the requested type
FODC0002A document cannot be read
FOER0000error() was called without a code

The tree and value classes of @exemplarjs/xdm throw an XdmError with the same standard codes when used directly, such as FORG0001 from a failed cast. XPathErrorCode, exported by both @exemplarjs/xpath and @exemplarjs/xdm, names the codes: XPathErrorCode.UNDECLARED_NAME is 'XPST0008'. See Getting started with XPath.

Other errors ​

API misuse throws one of these errors, which carry no code. See Errors and locations.

ErrorWhen
InvalidArgumentErrorAn option or argument value is not one the API accepts, such as an unknown output encoding
IllegalStateErrorA method is called in a state that does not permit it, such as elementText() when the current event is not a start tag
RangeErrorA position is out of range, or a number exceeds the range of the requested type
AsyncReaderRequiredErrorA synchronous reader encounters a resolver or source that returns its result asynchronously
PromiseNotAwaitedErrorA synchronous XPath evaluation encounters a resolver that returns a promise
DOMExceptionA DOM operation is not allowed, with the standard DOM error names

Released under the Apache License 2.0.