iOS Developer Library

Developer

Foundation Framework Reference NSError Class Reference

Options
Deployment Target:

On This Page
Language:

NSError

Inheritance


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.

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 NOfalse 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.

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

    Declaration

    Objective-C

    + (instancetype)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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    init(domain domain: String, code code: Int, userInfo dict: [NSObject : AnyObject]?)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • code code Property

    The error code. (read-only)

    Declaration

    Swift

    var code: Int { get }

    Objective-C

    @property(readonly) NSInteger code

    Discussion

    Note that errors are domain specific.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • domain domain Property

    A string containing the error domain. (read-only)

    Declaration

    Swift

    var domain: String { get }

    Objective-C

    @property(readonly, copy) NSString *domain

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • userInfo userInfo Property

    The user info dictionary. (read-only)

    Declaration

    Swift

    var userInfo: [NSObject : AnyObject]? { get }

    Objective-C

    @property(readonly, copy) NSDictionary *userInfo

    Discussion

    If the user info dictionary has not been set, this property is nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • A string to display in response to an alert panel help anchor button being pressed. (read-only)

    Declaration

    Swift

    var helpAnchor: String? { get }

    Objective-C

    @property(readonly, copy) NSString *helpAnchor

    Discussion

    The object in the user info dictionary for the key NSHelpAnchorErrorKey. If the user info dictionary doesn’t contain a value for NSHelpAnchorErrorKey, this property is nil.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • These keys may exist in the user info dictionary.

    Declaration

    Swift

    let NSLocalizedDescriptionKey: String let NSFilePathErrorKey: String let NSStringEncodingErrorKey: String let NSUnderlyingErrorKey: String let NSURLErrorKey: String let NSLocalizedFailureReasonErrorKey: String let NSLocalizedRecoverySuggestionErrorKey: String let NSLocalizedRecoveryOptionsErrorKey: String let NSRecoveryAttempterErrorKey: String let NSHelpAnchorErrorKey: String let NSURLErrorFailingURLErrorKey: String let NSURLErrorFailingURLStringErrorKey: String let NSURLErrorFailingURLPeerTrustErrorKey: String

    Objective-C

    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

      NSLocalizedDescriptionKey

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

      Available in iOS 2.0 and later.

    • NSErrorFailingURLStringKey

      NSErrorFailingURLStringKey

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

      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 iOS 2.0 and later.

      Deprecated in iOS 4.0.

    • NSFilePathErrorKey

      NSFilePathErrorKey

      Contains the file path of the error.

      The corresponding value is an NSString object.

      Available in iOS 2.0 and later.

    • NSStringEncodingErrorKey

      NSStringEncodingErrorKey

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

      Available in iOS 2.0 and later.

    • NSUnderlyingErrorKey

      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 iOS 2.0 and later.

    • NSURLErrorKey

      NSURLErrorKey

      The corresponding value is an NSURL object.

      Available in iOS 2.0 and later.

    • NSLocalizedFailureReasonErrorKey

      NSLocalizedFailureReasonErrorKey

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

      Available in iOS 2.0 and later.

    • NSLocalizedRecoverySuggestionErrorKey

      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 iOS 2.0 and later.

    • NSLocalizedRecoveryOptionsErrorKey

      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 iOS 2.0 and later.

    • NSRecoveryAttempterErrorKey

      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 iOS 2.0 and later.

    • NSHelpAnchorErrorKey

      NSHelpAnchorErrorKey

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

      Available in iOS 4.0 and later.

    • NSURLErrorFailingURLErrorKey

      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 iOS 4.0 and later.

    • NSURLErrorFailingURLStringErrorKey

      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 iOS 4.0 and later.

    • NSURLErrorFailingURLPeerTrustErrorKey

      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 iOS 4.0 and later.

  • The following error domains are predefined.

    Declaration

    Swift

    let NSPOSIXErrorDomain: String let NSOSStatusErrorDomain: String let NSMachErrorDomain: String

    Objective-C

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

    Constants

    • NSPOSIXErrorDomain

      NSPOSIXErrorDomain

      POSIX/BSD errors

      Available in iOS 2.0 and later.

    • NSOSStatusErrorDomain

      NSOSStatusErrorDomain

      Mac OS 9/Carbon errors

      Available in iOS 2.0 and later.

    • NSMachErrorDomain

      NSMachErrorDomain

      Mach errors

      Available in iOS 2.0 and later.

    Discussion

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