Skip to content

Errors and locations ​

When a document cannot be read, exemplar throws an error that identifies the problem and its location. This page covers the fields of the error, which errors a handler can intercept so that reading continues, and how to get the location of any event.

This catalog has an error on its third line: the title element is never closed.

xml
<catalog>
  <book id="b1"><title>Dune</title></book>
  <book id="b2"><title>Emma</book>
</catalog>

Reading it throws an XMLError:

ts
import { 
DocumentBuilder
} from '@exemplarjs/dom';
import {
XMLError
} from '@exemplarjs/xml';
try { new
DocumentBuilder
(
xml
).
parse
({
systemId
: 'file:///data/books.xml',
text
:
source
});
} catch (
error
) {
if (
error
instanceof
XMLError
) {
console
.
log
(
error
.
message
);
} else { throw
error
;
} } // WF_END_TAG_MISMATCH: Expected </title> (file:///data/books.xml 3:30)

The message is the error's code, a description, then the document's system id with the line and column. A document read without a systemId has only the line and column: (3:30).

What an error holds ​

Every problem in a document is reported as an XMLError, whichever API reads it. Its fields:

FieldHolds
codeA fixed identifier for the kind of problem, such as WF_END_TAG_MISMATCH. Test this, not the message.
messageThe code, the description and the location together, ready to log
descriptionThe description alone, such as Expected </title>, for composing a custom message
lineThe line, counting from 1
columnThe column, counting from 1
offsetThe offset from the start of the text, counting from 0
systemIdThe system id of the document, when the source had one; undefined otherwise
entitiesThe names of the entities the problem is inside, outermost first; usually empty

location returns line, column, offset and systemId as one object.

Columns and offsets count UTF-16 code units, as JavaScript strings do, so source.slice(error.offset) starts at the problem when source is the string that was parsed.

The codes are grouped by prefix: WF_ for XML that is not well formed, NS_ for namespaces, VC_ for validation, ENCODING_, LIMIT_, XINCLUDE_ and so on. Error codes lists every one. Each is also a member of the ErrorCode object, which gives editor completion:

ts
if (
error
instanceof
XMLError
&&
error
.
code
===
ErrorCode
.
WF_END_TAG_MISMATCH
) {
// An end tag is missing or misplaced. }

INFO

An XMLError has no stack trace beyond its first line. The relevant location is the one in the document, which the fields above provide.

Which problems stop reading ​

Each problem is a fatal error, a recoverable error or a warning. The kind determines whether reading can continue.

A fatal error means the document cannot be parsed. Usually it is not well formed: an unclosed tag, a disallowed character, or bytes that are invalid in the declared encoding. The input after that point cannot be interpreted reliably, so the error is thrown and reading stops. No option changes that.

A recoverable error means the document is well formed and can be read to the end, but violates a constraint beyond the syntax. The most common case is a document that does not match its DTD. A recoverable error is thrown too, unless an error handler with an error callback is supplied. In that case it is passed to the callback and reading continues.

A warning reports a construct that is permitted but probably unintended. Warnings are never thrown, and are discarded when there is no handler.

The table gives the kind of each group of codes. Several rows belong to features covered on later pages; each links to its page.

ProblemCodesKind
Malformed XML: tags, attributes, references, charactersWF_…Fatal error
A prefix that is not declared, and other namespace mistakesNS_…Fatal error
Bytes that do not fit the encoding, or an encoding that is not supportedENCODING_…Fatal error
A limit exceededLIMIT_…Fatal error
A <!DOCTYPE> when DTDs are refusedDOCTYPE_DISALLOWEDFatal error
An include that failsXINCLUDE_…Fatal error
A catalog with no match, under 'strict'CATALOG_NO_MATCHFatal error
A catalog file that cannot be readCATALOG_UNREADABLEFatal error
A read the access lists allow, with no resolverRESOLVER_MISSINGFatal error
The document does not match its DTDVC_…Recoverable error
A read asked of a resolver or catalog that the access lists refuseACCESS_REFUSEDRecoverable error
A document declared as UTF-16 with no byte-order markENCODING_UTF16_WITHOUT_BOMRecoverable error
An encoding given from outside that overrides the declared oneENCODING_CONFLICTWarning
A DTD that declares an entity, or an element's attribute, twiceDTD_DUPLICATE_…Warning
An xml:id that is repeated or not a valid nameXMLID_…Warning

With no resolver and no catalog, a reference to a file the access lists do not allow is not an error: the file is not read, and the document is read without it.

Handle errors yourself ​

The factory's errorHandler option takes an object with up to three callbacks, one per kind: fatalError, error for recoverable errors, and warning. Each callback receives the XMLError.

ts
import { 
XMLError
,
XMLInputFactory
} from '@exemplarjs/xml';
const
problems
:
XMLError
[] = [];
const
tolerant
= new
XMLInputFactory
({
errorHandler
: {
warning
: (
problem
) =>
console
.
warn
(
problem
.
message
),
error
: (
problem
) =>
problems
.
push
(
problem
), // collected, and reading continues
fatalError
: (
problem
) =>
console
.
error
(
problem
.
message
), // the error is thrown after this returns
}, });
CallbackCalled forWithout itWith it
warningWarningsThe warning is discardedIt is called; reading continues
errorRecoverable errorsThe error is thrownIt is called; reading continues
fatalErrorFatal errorsThe error is thrownIt is called first; the error is thrown all the same

All three callbacks are optional. The most common handler has only error, to collect validation errors, as Validating against a DTD shows.

To stop at a recoverable error, throw from error. The thrown value propagates to the code that is reading.

A SAX handler can define the same three callbacks itself, alongside startElement and the rest. Each one it defines is called instead of the factory's.

A failed reader stays failed ​

Once a reader has thrown an XMLError, it cannot continue. hasNext() returns false from then on, and next() throws the same error again; the reader does not skip the malformed content and resume.

ts
const 
reader
=
xml
.
createStreamReader
(
source
);
try { while (
reader
.
hasNext
())
reader
.
next
();
} catch (
error
) {
if (
error
instanceof
XMLError
)
console
.
log
(
error
.
code
); // WF_END_TAG_MISMATCH
}
reader
.
hasNext
(); // false
try {
reader
.
next
();
} catch (
error
) {
if (
error
instanceof
XMLError
)
console
.
log
(
error
.
code
); // WF_END_TAG_MISMATCH, again
}

The events reported before the error reflect the document up to that point, and the application may already have acted on them. If a document that fails must have no effect, read it to the end before acting on it, or build a tree, which either completes or throws.

Find where an event is ​

Every event has a location, not only errors. Locations are useful in application messages such as "the price on line 12 is not a number". These samples read the catalog above with its error corrected, and print where each title starts.

ts
const 
reader
=
xml
.
createStreamReader
({
systemId
: 'file:///data/books.xml',
text
:
source
});
while (
reader
.
hasNext
()) {
if (
reader
.
next
() ===
EventType
.
START_ELEMENT
&&
reader
.
localName
() === 'title') {
console
.
log
(
reader
.
location
());
} } // { line: 2, column: 17, offset: 26, systemId: 'file:///data/books.xml' } // { line: 3, column: 17, offset: 69, systemId: 'file:///data/books.xml' }
ts
for (const 
event
of
xml
.
createEventReader
({
systemId
: 'file:///data/books.xml',
text
:
source
})) {
if (
event
.
type
===
EventType
.
START_ELEMENT
&&
event
.
name
.
localName
=== 'title') {
console
.
log
(
event
.
location
);
} } // { line: 2, column: 17, offset: 26, systemId: 'file:///data/books.xml' } // { line: 3, column: 17, offset: 69, systemId: 'file:///data/books.xml' }
ts
let 
locator
: Locator;
new
SAXParser
(
xml
).
parse
(
{
systemId
: 'file:///data/books.xml',
text
:
source
},
{ // Called once, before anything else. Keep the locator: it always describes the current event.
setDocumentLocator
: (
given
) => (
locator
=
given
),
startElement
(
uri
,
localName
) {
if (
localName
=== 'title')
console
.
log
(
locator
.
lineNumber
,
locator
.
columnNumber
,
locator
.
systemId
);
}, } ); // 2 17 file:///data/books.xml // 3 17 file:///data/books.xml

A location is where the event starts: for a start tag, its <. It has the same four fields as an error: line, column, offset and systemId. The SAX locator names them lineNumber and columnNumber, and has no offset.

Tree nodes do not record their locations. To report the line of a node, record it while reading, before the tree is built.

Errors in your own code ​

An XMLError concerns the document. Two other classes concern the code that calls exemplar:

ClassCauseExample
XMLErrorThe documentA tag that is never closed
InvalidArgumentErrorAn invalid option or argumentA source object with neither text nor bytes
IllegalStateErrorA call that is invalid in the current stateelementText() when not at a start tag

All three are exported from @exemplarjs/xml, and each package that throws one exports it too.

ts
import { 
IllegalStateError
,
InvalidArgumentError
,
XMLError
} from '@exemplarjs/xml';
const
reader
=
xml
.
createStreamReader
('<title>Dune</title>');
try {
reader
.
elementText
(); // too early: the reader is not at the start tag yet
} catch (
error
) {
if (
error
instanceof
XMLError
)
console
.
log
('Bad document:',
error
.
message
);
else if (
error
instanceof
InvalidArgumentError
)
console
.
log
('Bad value:',
error
.
message
);
else if (
error
instanceof
IllegalStateError
)
console
.
log
('Bad timing:',
error
.
message
);
else throw
error
;
} // Bad timing: elementText() needs a START_ELEMENT

The last two indicate bugs in the calling code, not problems to report to the sender of the document. An index that is out of range, such as the fifth attribute of a start tag that has two, throws a built-in RangeError.

Errors from other parts of exemplar ​

A few parts have their own error class:

Next steps ​

Released under the Apache License 2.0.