Error objects thrown in the case of a program failure.

AnError object represents a program failure that the programmershould have avoided.

Examples include calling a function with invalid arguments,or even with the wrong number of arguments,or calling it at a time when it is not allowed.

These are not errors that a caller should expect or catch —if they occur, the program is erroneous,and terminating the program may be the safest response.

When deciding that a function should throw an error,the conditions where it happens should be clearly described,and they should be detectable and predictable,so the programmer using the function can avoid triggering the error.

Such descriptions often uses words like"must" or "must not" to describe the condition,and if you see words like that in a function's documentation,then not satisfying the requirementis very likely to cause an error to be thrown.

Example (fromString.contains):

`startIndex` must not be negative or greater than `length`.

In this case, an error will be thrown ifstartIndex is negativeor too large.

If the conditions are not detectable before calling a function,the called function should not throw anError.It may still throw,but the caller will have to catch the thrown value,effectively making it an alternative result rather than an error.If so, we consider the thrown object anexception rather than an error.The thrown object can choose to implementExceptionto document that it represents an exceptional, but not erroneous,occurrence, but being anException has no other effectthan documentation.

All non-null values can be thrown in Dart.Objectsextending theError class are handled specially:The first time they are thrown,the stack trace at the throw point is recordedand stored in the error object.It can be retrieved using thestackTrace getter.An error object that merely implementsError, and doesn't extend it,will not store the stack trace automatically.

Error objects are also used for system wide failureslike stack overflow or an out-of-memory situation,which the user is also not expected to catch or handle.

Since errors are not created to be caught,there is no need for subclasses to distinguish the errors.Instead subclasses have been created in order to make groupsof related errors easy to create with consistent error messages.For example, theString.contains method will use aRangeErrorif itsstartIndex isn't in the range0..length,which is easily created byRangeError.range(startIndex, 0, length).Catching specific subclasses ofError is not intended,and shouldn't happen outside of testing your own code.

Implementers

• AbstractClassInstantiationError
• ArgumentError
• AssertionError
• AsyncError
• ConcurrentModificationError
• JsonUnsupportedObjectError
• NoSuchMethodError
• OutOfMemoryError
• ParallelWaitError
• RemoteError
• StackOverflowError
• StateError
• TypeError
• UnimplementedError
• UnsupportedError

Constructors

Error()

Properties

hashCode→int

The hash code for this object.

no setterinherited

runtimeType→Type

A representation of the runtime type of the object.

no setterinherited

stackTrace→StackTrace?

The stack trace at the point where this error was first thrown.

no setter

Methods

noSuchMethod(Invocationinvocation)→ dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString()→String

A string representation of this object.

inherited

Operators

operator ==(Objectother)→bool

The equality operator.

inherited

Static Methods

safeToString(Object?object)→String

Safely convert a value to aString description.

throwWithStackTrace(Objecterror,StackTracestackTrace)→ Never

Throwserror with associated stack tracestackTrace.