NSError description/reason synthesis cheat sheet

When presenting errors in your app’s UI, NSError provides a surprising depth of functionality. Several of its key methods do more than simply look up the corresponding key in .userInfo, having a slightly more convoluted search routine that invents strings on your behalf some of the time.

Unfortunately the documentation is a bit spread between the doc sets and header files, and hard to remember. So, here's my handy cheat-sheet for how some methods lookup their result:

-localizedFailureReason

  1. Direct overrides in an NSError subclass (handy for generating your own string on-demand)
  2. NSLocalizedFailureReasonErrorKey in .userInfo
  3. For codes listed in FoundationErrors.h, Cocoa provides its own string
  4. Otherwise, nil


-localizedDescription

  1. Direct overrides in an NSError subclass
  2. NSLocalizedDescriptionKey in .userInfo
  3. For codes listed in FoundationErrors.h, Cocoa provides its own string that is often the same as or similar to ‑localizedFailureReason, but independent of it (i.e. a custom failure reason won't be integrated as part of this)
  4. A generic description — “The operation couldn't be completed.” — with the next sentence being:
    1. -localizedFailureReason if non-nil
    2. Otherwise, the error domain and code; domains listed in NSError.h get localized, e.g. “Cocoa” instead of “NSCocoaErrorDomain”
© Mike Abdullah 2007-2015