---

NSError Class Reference

Overview

An NSError object encapsulates richer and more extensible error information than is possible using only an error code or error string. The core attributes of an NSError object are an error domain (represented by a string), a domain-specific error code and a user info dictionary containing application specific information.

Several well-known domains are defined corresponding to Mach, POSIX, and OSStatus errors. Foundation error codes are found in the Cocoa error domain and documented in the Foundation Constants Reference. In addition, NSError allows you to attach an arbitrary user info dictionary to an error object, and provides the means to return a human-readable description for the error.

NSError is not an abstract class, and can be used directly. Applications may choose to create subclasses of NSError to provide better localized error strings by overriding localizedDescription.

In general, a method should signal an error condition by—for example—returning NO or nil rather than by the simple presence of an error object. The method can then optionally return an NSError object by reference, in order to further describe the error.

Adopted Protocols

• encodeWithCoder:

• initWithCoder:

• copyWithZone:

Tasks

Creating Error Objects

• + errorWithDomain:code:userInfo:
• – initWithDomain:code:userInfo:

Getting Error Properties

• – code
• – domain
• – userInfo

Getting a Localized Error Description

• – localizedDescription
• – localizedRecoveryOptions
• – localizedRecoverySuggestion
• – localizedFailureReason

Getting the Error Recovery Attempter

• – recoveryAttempter

Class Methods

errorWithDomain:code:userInfo:

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

+ (id)errorWithDomain:(NSString *)domain code:(NSInteger)code userInfo:(NSDictionary *)dict

Parameters

domain

The error domain—this can be one of the predefined NSError domains, or an arbitrary string describing a custom domain. domain must not be nil.

code

The error code for the error.

dict

The userInfo dictionary for the error. userInfo may be nil.

Return Value

An NSError object for domain with the specified error code and the dictionary of arbitrary data userInfo.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.
• Available in iPhone OS 2.0 and later.

Related Sample Code

• CoreRecipes
• CustomAtomicStoreSubclass
• iSpend
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus

Declared In

NSError.h

Instance Methods

code

Returns the receiver’s error code.

- (NSInteger)code

Return Value

The receiver’s error code.

Discussion

Note that errors are domain specific.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.
• Available in iPhone OS 2.0 and later.

See Also

• – localizedDescription
• – domain
• – userInfo

Related Sample Code

• Core Data HTML Store
• Departments and Employees
• ExtractMovieAudioToAIFF
• QTExtractAndConvertToAIFF
• QTExtractAndConvertToMovieFile

Declared In

NSError.h

domain

Returns the receiver’s error domain.

- (NSString *)domain

Return Value

A string containing the receiver’s error domain.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.
• Available in iPhone OS 2.0 and later.

See Also

• – code
• – localizedDescription
• – userInfo

Related Sample Code

• Departments and Employees

Declared In

NSError.h

initWithDomain:code:userInfo:

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

- (id)initWithDomain:(NSString *)domain code:(NSInteger)code userInfo:(NSDictionary *)dict

Parameters

domain

The error domain—this can be one of the predefined NSError domains, or an arbitrary string describing a custom domain. domain must not be nil.

code

The error code for the error.

dict

The userInfo dictionary for the error. userInfo may be nil.

Return Value

An NSError object initialized for domain with the specified error code and the dictionary of arbitrary data userInfo.

Discussion

This is the designated initializer for NSError.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.
• Available in iPhone OS 2.0 and later.

See Also

• + errorWithDomain:code:userInfo:

Related Sample Code

• BindingsJoystick
• CocoaEcho
• CocoaHTTPServer
• CocoaSOAP

Declared In

NSError.h

localizedDescription

Returns a string containing the localized description of the error.

- (NSString *)localizedDescription

Return Value

A string containing the localized description of the error.

By default this method returns the object in the user info dictionary for the key NSLocalizedDescriptionKey. If the user info dictionary doesn’t contain a value for NSLocalizedDescriptionKey, a default string is constructed from the domain and code.

Discussion

This method can be overridden by subclasses to present customized error strings.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.
• Available in iPhone OS 2.0 and later.

See Also

• – code
• – domain
• – userInfo

Related Sample Code

• CoreRecipes
• Departments and Employees
• NewsReader

Declared In

NSError.h

localizedFailureReason

Returns a string containing the localized explanation of the reason for the error.

- (NSString *)localizedFailureReason

Return Value

A string containing the localized explanation of the reason for the error. By default this method returns the object in the user info dictionary for the key NSLocalizedFailureReasonErrorKey.

Discussion

This method can be overridden by subclasses to present customized error strings.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – code
• – domain
• – userInfo

Related Sample Code

• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus

Declared In

NSError.h

localizedRecoveryOptions

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

- (NSArray *)localizedRecoveryOptions

Return Value

An array containing the localized titles of buttons appropriate for displaying in an alert panel. By default this method returns the object in the user info dictionary for the key NSLocalizedRecoveryOptionsErrorKey. If the user info dictionary doesn’t contain a value for NSLocalizedRecoveryOptionsErrorKey, nil is returned.

Discussion

The first string is the title of the right-most and default button, the second the one to the left of that, and so on. The recovery options should be appropriate for the recovery suggestion returned by localizedRecoverySuggestion. If the user info dictionary doesn’t contain a value for NSLocalizedRecoveryOptionsErrorKey, only an OK button is displayed.

This method can be overridden by subclasses to present customized recovery suggestion strings.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSError.h

localizedRecoverySuggestion

Returns a string containing the localized recovery suggestion for the error.

- (NSString *)localizedRecoverySuggestion

Return Value

A string containing the localized recovery suggestion for the error. By default this method returns the object in the user info dictionary for the key NSLocalizedRecoverySuggestionErrorKey. If the user info dictionary doesn’t contain a value for NSLocalizedRecoverySuggestionErrorKey, nil is returned.

Discussion

The returned string is suitable for displaying as the secondary message in an alert panel.

This method can be overridden by subclasses to present customized recovery suggestion strings.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSError.h

recoveryAttempter

Returns an object that conforms to the NSErrorRecoveryAttempting informal protocol.

- (id)recoveryAttempter

Return Value

An object that conforms to the NSErrorRecoveryAttempting informal protocol. By default this method returns the object for the user info dictionary for the key NSRecoveryAttempterErrorKey. If the user info dictionary doesn’t contain a value for NSRecoveryAttempterErrorKey, nil is returned.

Discussion

The recovery attempter must be an object that can correctly interpret an index into the array returned by localizedRecoveryOptions.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – localizedRecoveryOptions

Declared In

NSError.h

userInfo

Returns the receiver's user info dictionary.

- (NSDictionary *)userInfo

Return Value

The receiver's user info dictionary, or nil if the user info dictionary has not been set.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 installed.
• Available in Mac OS X v10.2.7 and later.
• Available in iPhone OS 2.0 and later.

See Also

• – code
• – domain
• – localizedDescription

Related Sample Code

• CoreRecipes
• Departments and Employees
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus

Declared In

NSError.h

Constants

User info dictionary keys

These keys may exist in the user info dictionary.

extern NSString *NSLocalizedDescriptionKey;
extern NSString *NSErrorFailingURLStringKey;
const NSString *NSFilePathErrorKey;
const NSString *NSStringEncodingErrorKey;
const NSString *NSUnderlyingErrorKey;
const NSString *NSURLErrorKey;
const NSString *NSLocalizedFailureReasonErrorKey;
const NSString *NSLocalizedRecoverySuggestionErrorKey;
const NSString *NSLocalizedRecoveryOptionsErrorKey;
const NSString *NSRecoveryAttempterErrorKey;

Constants

NSLocalizedDescriptionKey

The corresponding value is a localized string representation of the error that, if present, will be returned by localizedDescription.

Available in Mac OS X v10.2 and later.

Declared in NSError.h.

NSErrorFailingURLStringKey

The corresponding value is the URL that caused the error. This key is only present in the NSURLErrorDomain.

Available in Mac OS X v10.2 with Safari 1.0 installed.

Available in Mac OS X v10.2.7 and later.

Available in iPhone OS 2.0 and later.

Declared in NSURLError.h.

NSFilePathErrorKey

Contains the file path of the error.

The corresponding value is an NSString object.

Available in Mac OS X v10.4 and later.

Declared in NSError.h.

NSStringEncodingErrorKey

The corresponding value is an NSNumber object containing the NSStringEncoding value.

Available in Mac OS X v10.4 and later.

Declared in NSError.h.

NSUnderlyingErrorKey

The corresponding value is an error that was encountered in an underlying implementation and caused the error that the receiver represents to occur.

Available in Mac OS X v10.3 and later.

Declared in NSError.h.

NSURLErrorKey

The corresponding value is an NSURL object.

Available in Mac OS X v10.4 and later.

Declared in NSError.h.

NSLocalizedFailureReasonErrorKey

The corresponding value is a localized string representation containing the reason for the failure that, if present, will be returned by localizedFailureReason.

This string provides a more detailed explanation of the error than the description.

Available in Mac OS X v10.4 and later.

Declared in NSError.h.

NSLocalizedRecoverySuggestionErrorKey

The corresponding value is a string containing the localized recovery suggestion for the error.

This string is suitable for displaying as the secondary message in an alert panel.

Available in Mac OS X v10.4 and later.

Declared in NSError.h.

NSLocalizedRecoveryOptionsErrorKey

The corresponding value is an array containing the localized titles of buttons appropriate for displaying in an alert panel.

The first string is the title of the right-most and default button, the second the one to the left, and so on. The recovery options should be appropriate for the recovery suggestion returned by localizedRecoverySuggestion.

Available in Mac OS X v10.4 and later.

Declared in NSError.h.

NSRecoveryAttempterErrorKey

The corresponding value is an object that conforms to the NSErrorRecoveryAttempting informal protocol.

The recovery attempter must be an object that can correctly interpret an index into the array returned by recoveryAttempter.

Available in Mac OS X v10.4 and later.

Declared in NSError.h.

Declared In

NSError.h

Error Domains

The following error domains are predefined.

const NSString *NSPOSIXErrorDomain;
const NSString *NSOSStatusErrorDomain;
const NSString *NSMachErrorDomain;

Constants

NSPOSIXErrorDomain

POSIX/BSD errors

Available in Mac OS X v10.2 and later.

Declared in NSError.h.

NSOSStatusErrorDomain

Mac OS 9/Carbon errors

Available in Mac OS X v10.2 and later.

Declared in NSError.h.

NSMachErrorDomain

Mach errors

Available in Mac OS X v10.2 and later.

Declared in NSError.h.

Discussion

Additionally, the following error domain is defined by Core Foundation:

Declared In

NSError.h

---