Skip to: content, navigation

DOMException (W3C DOM Core object)

Spec
Version Depr.
DOM1 No
Browser support (more…)
IE7 FF1.5+ SA1.3+ OP9+
None Full Full Full

Example

var node = document.getElementsByTagName('h1').item(0);
var refnode = node.nextSibling;
var newnode = document.createTextNode('That is why you fail.');
node.insertBefore(newnode, refnode);

The example above shows an insertBefore operation that will fail, because refnode is not a child of node. That operation produces the following exception in Opera: 

Inline script thread
Error:
Unhandled Exception: [Object DOMException]
code: 8
message: NOT_FOUND_ERR

Description

The DOMException interface represents a processing error, for example when trying to create an invalid DOM, or passing a non-existent node as an argument to node manipulation methods. An exception is raised when an operation is impossible to perform, ie. in "exceptional" circumstances.

The DOM does not define an exception for every possible error that might occur, for example syntax errors in arguments are not included, and in such cases an implementation will use its own error reporting mechanism to deal with them.

: How DOM Exceptions are implemented in modern browsers

In practise, what we find is that most browsers implement DOM exceptions as part of their native mechanism, passing the exception code and message as the details of the error, along with any additional information the browser is able to provide (such as line number or stacktrace). Exceptions in JavaScript can be handled using the try...catch...finally construct.

Compatibility

Internet Explorer Firefox Safari Opera
5.5 6.0 7.0 1.5 2.0 3.0 1.3 2.0 3.0 9.0 9.5
None None None Full Full Full Full Full Full Full Full

Internet Explorer does not implement this interface, and uses its native error reporting syntax only; for example, the example above would throw Invalid argument). In XML a more informative description will be given — for this example, Insert position Node must be a Child of the Node to insert under.

: Caveat for Safari

Safari 1.3 and 2 do not report the error name, only the error code. However this is not documented as a bug because the specification does not define error names as properties of the DOMException object.

Constants

The interface defines ExceptionCode integers — exposed through the code property — to refer to each type of error; these are defined by the following constants:

INDEX_SIZE_ERR code 1
If an index is negative, or larger than the allowed value; for example using splitText with an offset argument larger than the length of the string.
DOMSTRING_SIZE_ERR code 2
The specified character data is too large for a DOMString. The size limit is implementation dependent, and not defined by the DOM (see DOM Core for details of each browser's limit).
HIERARCHY_REQUEST_ERR code 3
This node is not allowed to have children of the new node's type, or the new node is already an ancestor of this node; for example, attempting to append an Element node to a Text node.
WRONG_DOCUMENT_ERR code 4
Attempted to use a node in a document other than the one that created it; for example, using appendChild with a reference to a child node from another Document, rather than importing it first (using importNode).
INVALID_CHARACTER_ERR code 5
An illegal or invalid character is specified in a string that has limitations, such as an element name1.
NO_DATA_ALLOWED_ERR code 6
Data has been specified for a node that doesn't support data; for example an Element node does not itself contain data, it has child nodes which contain data.
NO_MODIFICATION_ALLOWED_ERR code 7
Attempted to modify a node that cannot be modified; for example, appending to a node that is readonly.
NOT_FOUND_ERR code 8
The referenced node does not exist; for example using insertBefore with a child node that is not a child of the reference node.
NOT_SUPPORTED_ERR code 9
The implementation does not support the specified operation; for example, when attempting to use a method of a node that is known but not implemented, an implementation may throw this error.
INUSE_ATTRIBUTE_ERR code 10
Attempted to add an attribute that's already in use; for example, using setAttributeNode with a reference to an Attr that is already in use on another Element, rather than cloning it first (using cloneNode).
INVALID_STATE_ERR code 11
Attempted to use an object that is not useable; this error is generally only thrown by an implementation when it's not able to perform a specific operation for internal reasons.
SYNTAX_ERR code 12
In invalid or illegal string has been specified; for example setting the selectorText property of a CSSStyleRule with an invalid CSS value.
INVALID_MODIFICATION_ERR code 13
Attempted to modify a node's type; for example, setting the cssText property of a CSSRule with a value that does not match the original rule's type (eg. setting style-rule values for an at-rule).
NAMESPACE_ERR code 14
An operation conflicts with the namespace rules; for example, using createElementNS with a malformed qualified name2.
INVALID_ACCESS_ERR code 15
A property or operation is not supported on the specified node; for example, attempting to use the getFloatValue method of CSSPrimitiveValue on a CSS property that doesn't contain a float value.

In this Section

  • code
    The ExceptionCode integer that refers to the type of a DOMException.

Footnotes

1 Names in XML can contain letters, numbers, underscores, periods (full stop) and hyphens; they cannot begin with a number, period or hyphen. They can also contain colons, however since colons are used in namespaces their more general use is discouraged.

2 For example, if the prefix is null; or if the prefix is xml and the namespaceURI is not http://www.w3.org/XML/1998/namespace

Previous / Next page

  1. Previous
  2. Next

Related reference material

User-contributed notes

There are no comments yet.

Add a note

To post a note on this topic, please log in with your SitePoint username and password. If you don't have an account yet, you can create a new account for free.

Related Products

Search