ProtocolSwift5.9.0

    Error

    A type representing an error value that can be thrown.

    protocol Error : Sendable

    Any type that declares conformance to the Error protocol can be used to represent an error in Swift’s error handling system. Because the Error protocol has no requirements of its own, you can declare conformance on any custom type you create.

    Using Enumerations as Errors

    Swift’s enumerations are well suited to represent simple errors. Create an enumeration that conforms to the Error protocol with a case for each possible error. If there are additional details about the error that could be helpful for recovery, use associated values to include that information.

    The following example shows an IntParsingError enumeration that captures two different kinds of errors that can occur when parsing an integer from a string: overflow, where the value represented by the string is too large for the integer data type, and invalid input, where nonnumeric characters are found within the input.

    enum IntParsingError: Error {
        case overflow
        case invalidInput(Character)
    }

    The invalidInput case includes the invalid character as an associated value.

    The next code sample shows a possible extension to the Int type that parses the integer value of a String instance, throwing an error when there is a problem during parsing.

    extension Int {
        init(validating input: String) throws {
            // ...
            let c = _nextCharacter(from: input)
            if !_isValid(c) {
                throw IntParsingError.invalidInput(c)
            }
            // ...
        }
    }

    When calling the new Int initializer within a do statement, you can use pattern matching to match specific cases of your custom error type and access their associated values, as in the example below.

    do {
        let price = try Int(validating: "$100")
    } catch IntParsingError.invalidInput(let invalid) {
        print("Invalid character: '\(invalid)'")
    } catch IntParsingError.overflow {
        print("Overflow error")
    } catch {
        print("Other error")
    }
    // Prints "Invalid character: '$'"

    Including More Data in Errors

    Sometimes you may want different error states to include the same common data, such as the position in a file or some of your application’s state. When you do, use a structure to represent errors. The following example uses a structure to represent an error when parsing an XML document, including the line and column numbers where the error occurred:

    struct XMLParsingError: Error {
        enum ErrorKind {
            case invalidCharacter
            case mismatchedTag
            case internalError
        }
    
        let line: Int
        let column: Int
        let kind: ErrorKind
    }
    
    func parse(_ source: String) throws -> XMLDoc {
        // ...
        throw XMLParsingError(line: 19, column: 5, kind: .mismatchedTag)
        // ...
    }

    Once again, use pattern matching to conditionally catch errors. Here’s how you can catch any XMLParsingError errors thrown by the parse(_:) function:

    do {
        let xmlDoc = try parse(myXMLData)
    } catch let e as XMLParsingError {
        print("Parsing error: \(e.kind) [\(e.line):\(e.column)]")
    } catch {
        print("Other error: \(error)")
    }
    // Prints "Parsing error: mismatchedTag [19:5]"

    Supertypes

    • protocol Sendable

      A type whose values can safely be passed across concurrency domains by copying.

    Available in Distributed

    Subtypes

    Available in _RegexParser

    Subtypes

    Available in Foundation

    Members

    Subtypes

    • protocol CustomNSError

      Describes an error type that specifically provides a domain, code, and user-info dictionary.

    • protocol LocalizedError

      Describes an error that provides localized messages describing why an error occurred and provides more information about the error.

    • protocol RecoverableError

      Describes an error that may be recoverable by presenting several potential recovery options to the user.

    Extension in AsyncSequenceValidation

    Subtypes

    Extension in TraceableErrors

    Members

    Subtypes

    Extension in MongoDriver

    Subtypes

    Extension in NIOExtras

    Subtypes

    Extension in NIOHPACK

    Subtypes

    Extension in NIOHTTP2

    Subtypes

    Extension in SymbolGraphLinker

    Subtypes

    Extension in UnidocLinker

    Subtypes

    Extension in GitHubAPI

    Subtypes

    Extension in Vapor

    Subtypes

    • protocol AbortError

      Errors conforming to this protocol will always be displayed by Vapor to the end-user (even in production mode where most errors are silenced).

    • protocol DebuggableError

      Debuggable provides an interface that allows a type to be more easily debugged in the case of an error.