TorError

Canonical error surface for every swift-tor failure mode.

enum TorError

Mentioned In

Using the Tor Control Protocol

Overview

TorError consolidates every expected failure across the embedded Tor process lifecycle, the control protocol, onion-service management, and low-level I/O into a single Sendable/Hashable enum — callers can switch exhaustively in one place instead of catching heterogeneous Error conformers from Foundation, POSIX, and the control layer. Associated-value payloads are String (or a (code: Int, message: String) tuple) so the concrete details of each failure are carried through without requiring downstream code to know the underlying machinery.

Cases are grouped by concern: Lifecycle covers TorError.alreadyStarted, TorError.notStarted, and TorError.startFailed(_:); Control protocol covers TorError.controlUnavailable, TorError.controlAuthFailed(_:), and TorError.controlProtocolError(code:message:); Onion service covers TorError.invalidServiceID(_:) and TorError.serviceAlreadyExists(_:); and General covers TorError.timeout, TorError.invalidResponse(_:), TorError.ioError(_:), and TorError.resourceExhausted(_:).

Note

Conformance is Error + Sendable + Hashable + CustomStringConvertible. Hashable is synthesised via SE-0185 across structural payloads, so two errors are equal iff both their cases and their associated strings/codes match verbatim.

Important

TorError does not yet conform to LocalizedError. Apple UI code that expects error.localizedDescription will fall back to the case name, not the human-readable description. Bridge explicitly via "\(error)" when rendering for users.

Topics

Lifecycle

case alreadyStarted
start() was called on a session already in .starting or .running.
case notStarted
An operation requiring a running Tor instance was invoked against an idle/stopped/failed session.
case startFailed(String)
Tor’s tor_run_main() returned non-zero during start or the start pipeline threw before the control socket became reachable.

Control protocol

case controlUnavailable
control() was called but no control client is bound.
case controlAuthFailed(String)
A AUTHENTICATE command was rejected by Tor (reply code 515).
case controlProtocolError(code: Int, message: String)
Tor returned a non-success reply to a control command.

Onion services

General

Rendering

var description: String
Human-readable, stable string representation of this error.