Mac Developer Library

Developer

Foundation Framework Reference NSError Class Reference

Options
Deployment Target:

On This Page
Language:

NSError

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

Inheritance


Import Statement


import Foundation @import Foundation;

Availability


Available in OS X v10.2 with Safari 1.0 installed.
Available in OS X v10.2.7 and later.
  • 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

    Availability

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

    Available in OS X v10.2.7 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

    import Foundation

    Availability

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

    Available in OS X v10.2.7 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

    import Foundation

    Availability

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

    Available in OS X v10.2.7 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

    import Foundation

    Availability

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

    Available in OS X v10.2.7 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

    import Foundation

    Availability

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

    Available in OS X v10.2.7 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

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • These keys may exist in the user info dictionary.

    Declaration

    Swift

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

    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 OS X v10.2 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 OS X v10.2 with Safari 1.0 installed.

      Available in OS X v10.2.7 and later.

      Deprecated in OS X v10.6.

    • NSFilePathErrorKey

      NSFilePathErrorKey

      Contains the file path of the error.

      The corresponding value is an NSString object.

      Available in OS X v10.4 and later.

    • NSStringEncodingErrorKey

      NSStringEncodingErrorKey

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

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

    • NSURLErrorKey

      NSURLErrorKey

      The corresponding value is an NSURL object.

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

    Import Statement

  • The following error domains are predefined.

    Declaration

    Swift

    let NSPOSIXErrorDomain: NSString! let NSOSStatusErrorDomain: NSString! let NSMachErrorDomain: NSString!

    Objective-C

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

    Constants

    • NSPOSIXErrorDomain

      NSPOSIXErrorDomain

      POSIX/BSD errors

      Available in OS X v10.2 and later.

    • NSOSStatusErrorDomain

      NSOSStatusErrorDomain

      Mac OS 9/Carbon errors

      Available in OS X v10.2 and later.

    • NSMachErrorDomain

      NSMachErrorDomain

      Mach errors

      Available in OS X v10.2 and later.

    Discussion

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

    Import Statement