Class

NSError

Information about an error condition including a domain, a domain-specific error code, and application-specific information.

Overview

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 (NSCocoaErrorDomain); error codes for the Cocoa Error Domain are documented in the Foundation Constants. There are also predefined domains corresponding to Mach (NSMachErrorDomain), POSIX (NSPOSIXErrorDomain), and Carbon (NSOSStatusErrorDomain) 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 localizedDescription.

Topics

Creating Error Objects

init(domain: String, code: Int, userInfo: [String : Any]? = nil)

Returns an NSError object initialized for a given domain and code with a given userInfo dictionary.

Getting Error Properties

var code: Int

The error code.

var domain: String

A string containing the error domain.

var userInfo: [String : Any]

The user info dictionary.

Getting a Localized Error Description

var localizedDescription: String

A string containing the localized description of the error.

var localizedRecoveryOptions: [String]?

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

var localizedRecoverySuggestion: String?

A string containing the localized recovery suggestion for the error.

var localizedFailureReason: String?

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

Providing Error User Info

class func setUserInfoValueProvider(forDomain: String, provider: ((Error, String) -> Any?)? = nil)

Specifies a block that is called from the implementations of localizedDescription, localizedFailureReason, localizedRecoverySuggestion, localizedRecoveryOptions, recoveryAttempter, and helpAnchor when the underlying value for any of those properties is not present in the userInfo dictionary of NSError instances with the specified domain.

class func userInfoValueProvider(forDomain: String)

Returns any user info provider specified by the setUserInfoValueProvider(forDomain:provider:) method for a given error domain.

struct ErrorUserInfoKey

These keys may exist in the user info dictionary.

Getting the Error Recovery Attempter

var recoveryAttempter: Any?

The object in the user info dictionary corresponding to the NSRecoveryAttempterErrorKey key.

NSErrorRecoveryAttempting

The NSErrorRecoveryAttempting informal protocol provides methods that allow your application to attempt to recover from an error. These methods are invoked when an NSError object is returned that specifies the implementing object as the error recoveryAttempter and the user has selected one of the error’s localized recovery options.

Displaying a Help Anchor

var helpAnchor: String?

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

Error Domains

let NSOSStatusErrorDomain: String

Mac OS 9/Carbon errors

let NSURLErrorDomain: String

URL loading system errors

let NSStreamSOCKSErrorDomain: String

The error domain used by NSError when reporting SOCKS errors.

let NSStreamSocketSSLErrorDomain: String

The error domain used by NSError when reporting SSL errors.

Error Codes

struct CocoaError

Describes errors within the Cocoa error domain.

struct MachError

Describes an error in the Mach error domain.

struct POSIXError

Describes an error in the POSIX error domain.

NSError Codes

NSError codes in the Cocoa error domain.

See Also

User-Relevant Errors

protocol Error

A type representing an error value that can be thrown.

protocol LocalizedError

A specialized error that provides localized messages describing the error and why it occurred.

protocol RecoverableError

A specialized error that may be recoverable by presenting several potential recovery options to the user.

protocol CustomNSError

A specialized error that provides a domain, error code, and user-info dictionary.