In this article I’d like to show some implementation details about Error type in Swift and how one can leverage localizedDescription property (and how to actually make it work). On top of that I’d like to show you a little tip on how you could implement extendable error messaging in your framework.

Error reporting to user

Often errors are a result of user action - it may be a simple network request that failed, it could be an error during user input validation etc. Regardless of what went wrong, you probably want to update your UI layer to reflect such incident. It could be either with an alert if an error occurred during an attempt to perform some action, other times you may need to change the whole view if the error affects current state of data.

Error handling

As a Swift developer you probably are already familiar with native error handling mechanisms, but let’s recap it briefly for those who are not that familiar with the concept.

Often when you’re writing a function which input must meet certain criteria, or a method that may fail depending on the state of the type it’s part of, you mark such function with the throws decorator. This basically informs the callee that the execution of function may fail. Swift defines a dedicated protocol type Error which represents types that can be thrown by function. When function throws an error the callee does not receive its result, but is expected to handle the error instead.

Given a function that can throw an error, like:

1

func doSomething() throws 

The callee will probably wrap it up in a do-catch expression:

1
2
3
4
5

do {
    try doSomething() 
} catch {
    // handle error here
} 

There may be cases where the one calling function doesn’t really care about what went wrong, but rather about the actual result only. In Swift this can be easily expressed with the try? keyword, that will return the function result wrapped in the Optional type. There’s also an expression matching the implicitly unwrapped optionals - try!. In many cases you probably also use the Optional type, which actually is pretty similar to function that throws. The difference is that there’s no particular error that has to be handled.

Error type in Swift

If you take a look at the type declaration in Xcode documentation you can see that it’s not very complex. The type itself doesn’t define any properties besides for localizedDescription: String and has no methods.

That’s all you can find in the documentation, but as Swift is open-source we can have a look at actual type definition, which is as follows¹:

1
2
3
4
5

public protocol Error {
  var _domain: String { get }
  var _code: Int { get }
  var _userInfo: AnyObject? { get }
}

Those properties have default implementations, that’s why whenever you make your custom error type conform to the protocol you don’t need to implement them yourself. It’s important to note here that those properties are underscored, meaning they are implementation detail of the compiler, providing your own _domain, or _code shouldn’t probably break anything, but using custom _userInfo implementation may break things in runtime so you probably shouldn’t overwrite it.

All those properties serve as a base for providing the Error type interoperability with the NSError type known from Objective-C.

User messages

Whether you’re a library author, or it’s for the needs of an application you’re working on, you probably want to provide consistent error messaging.

In some cases you may be able to provide one, or few messages, to cover various scenarios. Say there was a network request that failed, maybe it was your server failure, maybe there was an issue with SSL certificate, maybe response that you received wasn’t what you expected in your code - in either of those cases you probably can use some standard error message that simply states that something went wrong with server communication. That’s totally fine, you may want to track such incidents, but users probably don’t want to know what was the low level source of the error, it only matters if given operation finished successfully or not.

There can be some other cases though, where general error messages are not sufficient. That often happens when there’s an input validation required. Whether it’s from the user itself, or maybe when you’re a library author and you need to validate input data for your public API functions.

Depending on your case you may want to provide some standard error messages that can be shown to the user directly in your custom error type definition. That way you could make sure they are consistent and that you can just change them in one place whenever your error type definition changes, to avoid repetitive work.

Messages in Cocoa

In Cocoa, the standard way of passing error information is the NSError type. Subclasses of this type can override the default implementation of localizedDescription property and provide some standard localised messages for errors of given domain. This is also how Apple provides localisation of the Cocoa errors.

With errors that do not explicitly provide localised error messages, Foundation has standard error message:

1
2
3
4
5
6
7

import Foundation 

enum SomeError: Swift.Error {
    case first
}

print(SomeError.first.localizedDescription)

This snippet will print The operation couldn’t be completed. (Run.SomeError error 0.) in console. Where Run.SomeError is the error’s domain and 0 is the code, here they are automatically generated by the compiler.

You could extend the type and provide your own description like that:

1
2
3
4
5
6
7
8

extension SomeError {
    var localizedDescription: String {
        switch self {
        case .first:
            return "First error occurred"    
        } 
    }  
}

Now if you call print(SomeError.first.localizedDescription), the compiler will print your own message.

Great. Let’s use it in code.
You define a new complex task. At some point you need to throw the error though. Now you no longer have to handle this error explicitly at the callee side when updating UI, you should then just be able to use the property and directly display its output to the user.

1
2
3

func someComplexTask() throws {
    throw SomeError.first
} 

At least that’s what I thought. There’s a catch.

Let’s test this function:

1
2
3
4
5
6
7

func testComplexTaskMessage() {
    do {
        try someComplexTask() 
    } catch {
        XCTAssertEqual(error.localizedDescription, "First error occurred")
    }
}

Unfortunately this will fail, because the description was actually the standard one. How, you may think. Well, the issue is caused by the compiler dispatch approach. Function in extensions of Swift protocol types are dispatched statically. Within the catch expression, error value is of the existential type Error, so when localizedDescription is called the compiler is using the standard implementation provided in the Error type extension itself rather then using the one provided on concrete type implementation. This would work as expected if localizedDescription computed property was part of the Error protocol requirement, but it’s not, the default implementation is only provided in the type extension.

If the test was using concrete error type, then it would pass:

1
2
3
4
5
6
7
8

do {
    try someComplexTask()
} catch let error as SomeError {
    XCTAssertEqual(error.localizedDescription, "First error occurred")
} catch {
    XCTFail()
}

Luckily there’s a solution for that without any custom extensions to the Error protocol, one should use LocalizedError instead.

The type is defined as follows, in Foundation²:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

public protocol LocalizedError : Error {
    /// A localized message describing what error occurred.
    var errorDescription: String? { get }

    /// A localized message describing the reason for the failure.
    var failureReason: String? { get }

    /// A localized message describing how one might recover from the failure.
    var recoverySuggestion: String? { get }

    /// A localized message providing "help" text if the user requests help.
    var helpAnchor: String? { get }
}

Instead of providing custom implementation of the localizedDescription of the Error protocol, you need to implement the LocalizedError protocol and return your error message in the errorDescription property.

Fluent error localisation in frameworks

If you’re developing some 3rd party library whether in open-source or for internal needs of your company, you may want to consider providing the ability of extendable error messaging through the native localisation mechanisms.

Normally when you want to provide ability to localise your library, you’re probably using direct calls to NSLocalizedString. If you provide the localisation on your own, you have to do a bit more, so first get the bundle reference for your framework and then localise any text, probably like that:

1
2

let bundle = Bundle(identifier: "your-bundle-id")!
bundle.localizedString... 

It is possible to join those two approaches to provide some default localisation and keep the possibility for the library user to define their own translation. You could encapsulate it as follows:

1
2
3
4
5
6
7

private let kLibraryBundle = Bundle(identifier: "your-bundle-id")!
private let kMainBundle = Bundle.main

func localizedString(forKey key: String, default: String?) -> String {
    let base = kLibraryBundle.localizedString(forKey: key, value: `default`, table: nil)
    return kMainBundle.localizedString(forKey: key, value: base, table: "your-bundle-id") 
} 

Note the localisation call using the main bundle, you can pass some arbitrary argument, maybe your bundle id or library name, to the table argument. That will enforce the client to put all the custom localisation of your library into separate file, so there will be no overlapping of your and the client custom keys.

Thanks for reading! If you’ve got any questions, comments, or general feedback, you can find all my social links at the bottom of the page.