An NSError object encapsulates information about an error condition in an extendable, object-oriented manner. It consists of a predefined error domain, a domain-specific error code, and a user info dictionary containing application-specific information.


Objective-C methods can signal an error condition by returning an NSError object by reference, which provides additional information about the kind of error and any underlying cause, if one can be determined. An NSError object may also provide localized error descriptions suitable for display to the user in its user info dictionary. See Error Handling Programming Guide for more information.

Methods in Foundation and other Cocoa frameworks most often produce errors in the Cocoa error domain (NSCocoa​Error​Domain); error codes for the Cocoa Error Domain are documented in the Foundation Constants. There are also predefined domains corresponding to Mach (NSMach​Error​Domain), POSIX (NSPOSIXError​Domain), and Carbon (NSOSStatus​Error​Domain) errors.

NSError is “toll-free bridged” with its Core Foundation counterpart, CFError. See Toll-Free Bridging for more information.

Subclassing Notes

Applications may choose to create subclasses of NSError, for example, to provide better localized error strings by overriding localized​Description.


Creating Error Objects

init(domain:​ String, code:​ Int, user​Info:​ [Any​Hashable :​ Any]? = nil)

Returns an NSError object initialized for a given domain and code with a given user​Info dictionary.

Getting Error Properties

var code:​ Int

The error code.

var domain:​ String

A string containing the error domain.

Getting a Localized Error Description

var localized​Description:​ String

A string containing the localized description of the error.

var localized​Recovery​Options:​ [String]?

An array containing the localized titles of buttons appropriate for displaying in an alert panel.

var localized​Recovery​Suggestion:​ String?

A string containing the localized recovery suggestion for the error.

var localized​Failure​Reason:​ String?

A string containing the localized explanation of the reason for the error.

Providing Error User Info

class func set​User​Info​Value​Provider(for​Domain:​ String, provider:​ ((Error, String) -> Any?)? = nil)

Specifies a block that is called from the implementations of localized​Description, localized​Failure​Reason, localized​Recovery​Suggestion, localized​Recovery​Options, recovery​Attempter, and help​Anchor when the underlying value for any of those properties is not present in the user​Info dictionary of NSError instances with the specified domain.

Getting the Error Recovery Attempter

var recovery​Attempter:​ Any?

The object in the user info dictionary corresponding to the NSRecovery​Attempter​Error​Key key.

Displaying a Help Anchor

var help​Anchor:​ String?

A string to display in response to an alert panel help anchor button being pressed.


User info dictionary keys

These keys may exist in the user info dictionary.

Error Domains

The following error domains are predefined.