description

# Error class Null safety

Error objects thrown in the case of a program failure.

An `Error` object represents a program failure that the programmer should 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 throws 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 requirement is very likely to cause an error to be thrown.

Example (from String.contains):

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

In this case, an error will be thrown if `startIndex` is negative or too large.

If the conditions are not detectable before calling a function, the called function should not throw an `Error`. It may still throw a value, but the caller will have to catch the thrown value, effectively making it an alternative result rather than an error. The thrown object can choose to implement Exception to document that it represents an exceptional, but not erroneous, occurrence, but it has no other effect than documentation.

All non-`null` values can be thrown in Dart. Objects extending `Error` are handled specially: The first time they are thrown, the stack trace at the throw point is recorded and stored in the error object. It can be retrieved using the stackTrace getter. An error object that merely implements `Error`, and doesn't extend it, will not store the stack trace automatically.

Error objects are also used for system wide failures like stack overflow or an out-of-memory situation.

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 groups of related errors easy to create with consistent error messages. For example, the String.contains method will use a RangeError if its `startIndex` isn't in the range `0..length`, which is easily created by `new RangeError.range(startIndex, 0, length)`.

Implementers
  - AbstractClassInstantiationError
  - ArgumentError
  - AssertionError
  - AsyncError
  - CastError
  - ConcurrentModificationError
  - CyclicInitializationError
  - FallThroughError
  - JsonUnsupportedObjectError
  - LateInitializationError
  - NoSuchMethodError
  - NullThrownError
  - OutOfMemoryError
  - RemoteError
  - StackOverflowError
  - StateError
  - TypeError
  - UnimplementedError
  - UnsupportedError

## Constructors

Error()

## Properties

hashCode → int
  The hash code for this object. [...]
  read-only, inherited
runtimeType → Type
  A representation of the runtime type of the object.
  read-only, inherited
stackTrace → StackTrace?
  read-only

## Methods

noSuchMethod(Invocation invocation) → dynamic
  Invoked when a non-existent method or property is accessed. [...]
  inherited
toString() → String
  Returns a string representation of this object.
  inherited

## Operators

operator ==(Object other) → bool
  The equality operator. [...]
  inherited

## Static Methods

safeToString(Object? object) → String
  Safely convert a value to a String description. [...]