<!--
{
  "availability" : [

  ],
  "documentType" : "symbol",
  "framework" : "Tor",
  "identifier" : "/documentation/Tor/TorError",
  "metadataVersion" : "0.1.0",
  "role" : "Enumeration",
  "symbol" : {
    "kind" : "Enumeration",
    "modules" : [
      "Tor"
    ],
    "preciseIdentifier" : "s:3Tor0A5ErrorO"
  },
  "title" : "TorError"
}
-->

# TorError

Canonical error surface for every swift-tor failure mode.

```
enum TorError
```

## 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`](/documentation/Tor/TorError/alreadyStarted), [`TorError.notStarted`](/documentation/Tor/TorError/notStarted), and [`TorError.startFailed(_:)`](/documentation/Tor/TorError/startFailed(_:));
**Control protocol** covers [`TorError.controlUnavailable`](/documentation/Tor/TorError/controlUnavailable),
[`TorError.controlAuthFailed(_:)`](/documentation/Tor/TorError/controlAuthFailed(_:)), and [`TorError.controlProtocolError(code:message:)`](/documentation/Tor/TorError/controlProtocolError(code:message:));
**Onion service** covers [`TorError.invalidServiceID(_:)`](/documentation/Tor/TorError/invalidServiceID(_:)) and
[`TorError.serviceAlreadyExists(_:)`](/documentation/Tor/TorError/serviceAlreadyExists(_:)); and **General** covers
[`TorError.timeout`](/documentation/Tor/TorError/timeout), [`TorError.invalidResponse(_:)`](/documentation/Tor/TorError/invalidResponse(_:)), [`TorError.ioError(_:)`](/documentation/Tor/TorError/ioError(_:)), and
[`TorError.resourceExhausted(_:)`](/documentation/Tor/TorError/resourceExhausted(_:)).

> Note: Conformance is `Error` + `Sendable` + `Hashable` +
> `CustomStringConvertible`. `Hashable` is synthesised via
> [SE-0185](https://github.com/swiftlang/swift-evolution/blob/master/proposals/0185-synthesize-equatable-hashable.md)
> 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 ``doc://Tor/documentation/Tor/TorError/description``. Bridge
> explicitly via `"\(error)"` when rendering for users.

## Topics

### Lifecycle

[`TorError.alreadyStarted`](/documentation/Tor/TorError/alreadyStarted)

[`start()`](/documentation/Tor/TorClient/start()) was called on a session already in
`.starting` or `.running`.

[`TorError.notStarted`](/documentation/Tor/TorError/notStarted)

An operation requiring a running Tor instance was invoked against
an idle/stopped/failed session.

[`TorError.startFailed(_:)`](/documentation/Tor/TorError/startFailed(_:))

Tor’s `tor_run_main()` returned non-zero during start or the
start pipeline threw before the control socket became reachable.

### Control protocol

[`TorError.controlUnavailable`](/documentation/Tor/TorError/controlUnavailable)

[`control()`](/documentation/Tor/TorClient/control()) was called but no control client is bound.

[`TorError.controlAuthFailed(_:)`](/documentation/Tor/TorError/controlAuthFailed(_:))

A `AUTHENTICATE` command was rejected by Tor (reply code 515).

[`TorError.controlProtocolError(code:message:)`](/documentation/Tor/TorError/controlProtocolError(code:message:))

Tor returned a non-success reply to a control command.

### Onion services

[`TorError.invalidServiceID(_:)`](/documentation/Tor/TorError/invalidServiceID(_:))

The supplied `.onion` service ID failed validation.

[`TorError.serviceAlreadyExists(_:)`](/documentation/Tor/TorError/serviceAlreadyExists(_:))

`ADD_ONION` against a pre-existing service ID (Tor reply 550 or 554).

### General

[`TorError.timeout`](/documentation/Tor/TorError/timeout)

A bounded wait elapsed without the awaited condition being met.

[`TorError.invalidResponse(_:)`](/documentation/Tor/TorError/invalidResponse(_:))

A control-protocol reply or async event could not be parsed.

[`TorError.ioError(_:)`](/documentation/Tor/TorError/ioError(_:))

A POSIX I/O operation against the control socket or data directory
failed.

[`TorError.resourceExhausted(_:)`](/documentation/Tor/TorError/resourceExhausted(_:))

Tor reported resource exhaustion (Tor reply 451) — out of file
descriptors, memory, or entry guards.

### Rendering

[`description`](/documentation/Tor/TorError/description)

Human-readable, stable string representation of this error.