NSError Class Reference

Inherits from
NSObject
Conforms to
NSCopying
NSSecureCoding
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.2 with Safari 1.0 installed.
Available in OS X v10.2.7 and later.
Companion guide
Error Handling Programming Guide
Declared in
NSError.h
NSURLError.h
Related sample code

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.

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

Adopted Protocols

NSCoding
NSCopying

Tasks

Creating Error Objects

Getting Error Properties

Getting a Localized Error Description

Getting the Error Recovery Attempter

Displaying a Help Anchor

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. See “Error Domains” for a list of predefined domains.

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 OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
Related Sample Code
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 OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
See Also
Related Sample Code
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 OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
NSError.h

helpAnchor

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

- (NSString *)helpAnchor
Return Value

An NSString that the alert panel will include a help anchor button with that value.

Discussion

If this method returns a non-nil value for an error being presented by alertWithError:, the alert panel will include a help anchor button that can display this string.

The best way to get a value to return for this method is to specify it as the value of NSHelpAnchorErrorKey in the NSError object’s userInfo dictionary; or the method can be overridden.

Availability
  • Available in OS X v10.6 and later.
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. See “Error Domains” for a list of predefined domains.

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 OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
See Also
Related Sample Code
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 OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
See Also
Related Sample Code
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 OS X v10.4 and later.
See Also
Related Sample Code
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 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 OS X v10.4 and later.
Related Sample Code
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 OS X v10.4 and later.
See Also
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 OS X v10.2 with Safari 1.0 installed.
  • Available in OS X v10.2.7 and later.
See Also
Related Sample Code
Declared In
NSError.h

Constants

User info dictionary keys

These keys may exist in the user info dictionary.

NSString * const NSLocalizedDescriptionKey;
NSString * const NSErrorFailingURLStringKey;
NSString * const NSFilePathErrorKey;
NSString * const NSStringEncodingErrorKey;
NSString * const NSUnderlyingErrorKey;
NSString * const NSURLErrorKey;
NSString * const NSLocalizedFailureReasonErrorKey;
NSString * const NSLocalizedRecoverySuggestionErrorKey;
NSString * const NSLocalizedRecoveryOptionsErrorKey;
NSString * const NSRecoveryAttempterErrorKey;
NSString * const NSHelpAnchorErrorKey;
NSString * const NSURLErrorFailingURLErrorKey;
NSString * const NSURLErrorFailingURLStringErrorKey;
NSString * const NSURLErrorFailingURLPeerTrustErrorKey;
Constants
NSLocalizedDescriptionKey

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

Available in 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. (Deprecated. This constant is deprecated in OS X v10.6, and is superseded by NSURLErrorFailingURLStringErrorKey.)

This constant is deprecated in OS X v10.6, and is superseded by NSURLErrorFailingURLStringErrorKey. Both constants refer to the same value for backward-compatibility, but the new symbol name has a better prefix.

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

Available in OS X v10.2.7 and later.

Deprecated in OS X v10.6.

Declared in NSURLError.h.

NSFilePathErrorKey

Contains the file path of the error.

The corresponding value is an NSString object.

Available in OS X v10.4 and later.

Declared in NSError.h.

NSStringEncodingErrorKey

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

Available in 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 OS X v10.3 and later.

Declared in NSError.h.

NSURLErrorKey

The corresponding value is an NSURL object.

Available in 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 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 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 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 OS X v10.4 and later.

Declared in NSError.h.

NSHelpAnchorErrorKey

The corresponding value is an NSString containing the localized help corresponding to the help button. See helpAnchor for more information.

Available in OS X v10.6 and later.

Declared in NSError.h.

NSURLErrorFailingURLErrorKey

The corresponding value is an NSURL containing the URL which caused a load to fail. This key is only present in the NSURLErrorDomain.

Available in OS X v10.6 and later.

Declared in NSURLError.h.

NSURLErrorFailingURLStringErrorKey

The corresponding value is an NSString object for the URL which caused a load to fail. This key is only present in the NSURLErrorDomain.

This constant supersedes NSErrorFailingURLStringKey, which was deprecated in OS X v10.6. Both constants refer to the same value for backward-compatibility, but this symbol name has a better prefix.

Available in OS X v10.6 and later.

Declared in NSURLError.h.

NSURLErrorFailingURLPeerTrustErrorKey

The corresponding value is the SecTrustRef object representing the state of a failed SSL handshake. This key is only present in the NSURLErrorDomain.

Available in OS X v10.6 and later.

Declared in NSURLError.h.

Error Domains

The following error domains are predefined.

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

POSIX/BSD errors

Available in OS X v10.2 and later.

Declared in NSError.h.

NSOSStatusErrorDomain

Mac OS 9/Carbon errors

Available in OS X v10.2 and later.

Declared in NSError.h.

NSMachErrorDomain

Mach errors

Available in OS X v10.2 and later.

Declared in NSError.h.

Discussion

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

CFStreamErrorDomainDefines constants for values returned in the domain field of the CFStreamError structure.
Declared In
NSError.h


© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-09-01)

Did this document help you? Yes It's good, but... Not helpful...