Class

NSError

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

Declaration

@interface NSError : NSObject

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, CFErrorRef. 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

+ errorWithDomain:code:userInfo:

Creates and initializes an NSError object for a given domain and code with a given userInfo dictionary.

- initWithDomain:code:userInfo:

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

Getting Error Properties

code

The error code.

domain

A string containing the error domain.

userInfo

The user info dictionary.

Getting a Localized Error Description

localizedDescription

A string containing the localized description of the error.

localizedRecoveryOptions

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

localizedRecoverySuggestion

A string containing the localized recovery suggestion for the error.

localizedFailureReason

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

Providing Error User Info

+ setUserInfoValueProviderForDomain:provider:

Specifies a block to call when the corresponding property is not present in the user info dictionary.

+ userInfoValueProviderForDomain:

Returns any user info provider specified for a given error domain.

NSErrorUserInfoKey

These keys may exist in the user info dictionary.

Getting the Error Recovery Attempter

recoveryAttempter

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

NSErrorRecoveryAttempting

A set of methods that provide options to recover from an error.

Displaying a Help Anchor

helpAnchor

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

Supporting Types

Error Domains

NSCocoaErrorDomain

Cocoa errors

NSPOSIXErrorDomain

POSIX/BSD errors

NSOSStatusErrorDomain

Mac OS 9/Carbon errors

NSURLErrorDomain

URL loading system errors

NSStreamSOCKSErrorDomain

The error domain used by NSError when reporting SOCKS errors.

NSStreamSocketSSLErrorDomain

The error domain used by NSError when reporting SSL errors.

Error Codes

NSError Codes

Error codes in the Cocoa error domain.

Type Methods

+ fileProviderErrorForCollisionWithItem:

Returns a properly formatted error object with a NSFileProviderItemCollisionError error code.

Relationships

Inherits From

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software