testcontainer/error

Types

Error

Every error returned by the public API is one of these variants. Each carries enough context to diagnose the problem without scraping logs.

pub type Error {
  DockerUnavailable(socket_path: String, reason: String)
  ImagePullFailed(image: String, reason: String)
  ContainerCreateFailed(image: String, reason: String)
  ContainerStartFailed(container_id: String, reason: String)
  ContainerStopFailed(container_id: String, reason: String)
  WaitTimedOut(strategy_description: String, elapsed_ms: Int)
  WaitFailed(strategy_description: String, reason: String)
  ExecFailed(
    container_id: String,
    cmd: List(String),
    exit_code: Int,
    stderr: String,
  )
  PortNotMapped(container_port: Int)
  FileCopyFailed(path: String, reason: String)
  PortMappingParseFailed(container_id: String, reason: String)
  DockerApiError(
    method: String,
    path: String,
    status: Int,
    body: String,
  )
  InvalidImageRef(raw: String)
  InvalidPort(number: Int)
}

Constructors

```
DockerUnavailable(socket_path: String, reason: String)
```
The Docker daemon could not be reached on the configured socket.
```
ImagePullFailed(image: String, reason: String)
```
The image could not be pulled (network error, auth required, not found).
```
ContainerCreateFailed(image: String, reason: String)
```
POST /containers/create returned an error or the response could not be parsed.

ContainerStartFailed(container_id: String, reason: String)

POST /containers/{id}/start returned an error.

ContainerStopFailed(container_id: String, reason: String)

POST /containers/{id}/stop returned an error.

```
WaitTimedOut(strategy_description: String, elapsed_ms: Int)
```
A wait strategy did not succeed within its configured timeout. elapsed_ms is the actual elapsed wall-clock time.
```
WaitFailed(strategy_description: String, reason: String)
```
A wait strategy reported a transient failure (the poll loop will retry until the deadline; this variant is also returned when the deadline is reached without success for non-timeout reasons).
```
ExecFailed(
  container_id: String,
  cmd: List(String),
  exit_code: Int,
  stderr: String,
)
```
An exec call failed at the Docker API level (not to be confused with a non-zero exit code, which is returned via exec.ExecResult).
```
PortNotMapped(container_port: Int)
```
The requested container port is not in the spec’s port mapping.
```
FileCopyFailed(path: String, reason: String)
```
copy_file_to/3 failed (read error, tar error, HTTP error).
```
PortMappingParseFailed(container_id: String, reason: String)
```
Docker inspect JSON was received but NetworkSettings.Ports could not be decoded into a usable host-port mapping.
```
DockerApiError(
  method: String,
  path: String,
  status: Int,
  body: String,
)
```
A Docker Engine API call returned an unexpected non-2xx status that did not map to a more specific variant above.
```
InvalidImageRef(raw: String)
```
The given image reference is malformed (currently used for CR/LF validation; reserved for future stricter parsing).
```
InvalidPort(number: Int)
```
A port number outside the valid TCP/UDP range (1..=65535).