Search documentation of bb

# Error Types Reference

Copy Markdown View Source

Structured error types in BB. All errors implement the `BB.Error.Severity` protocol.

## Severity Levels

Level | Description
--- | ---
`:critical` | Immediate safety response required
`:error` | Operation failed, may retry or degrade
`:warning` | Unusual condition, operation continues

## Hardware Errors

Communication failures with physical devices.

Class: `:hardware`

### BusError

Communication bus failure.

Module: `BB.Error.Hardware.BusError`

Fields:

Field | Type | Description
--- | --- | ---
`bus` | `string` | Bus identifier (e.g., "i2c-1")
`reason` | `term` | Underlying error

Severity: `:error`

### DeviceError

Device-level failure.

Module: `BB.Error.Hardware.DeviceError`

Fields:

Field | Type | Description
--- | --- | ---
`device` | `term` | Device identifier
`reason` | `term` | Error details

Severity: `:error`

### Disconnected

Device unexpectedly disconnected.

Module: `BB.Error.Hardware.Disconnected`

Fields:

Field | Type | Description
--- | --- | ---
`device` | `term` | Device identifier

Severity: `:error`

### Timeout

Hardware communication timeout.

Module: `BB.Error.Hardware.Timeout`

Fields:

Field | Type | Description
--- | --- | ---
`device` | `term` | Device identifier
`operation` | `atom` | Operation that timed out

Severity: `:error`

## Safety Errors

Safety system violations.

Class: `:safety`

All safety errors have severity `:critical`.

### CollisionRisk

Collision detected or imminent.

Module: `BB.Error.Safety.CollisionRisk`

Fields:

Field | Type | Description
--- | --- | ---
`link` | `atom` | Link at risk
`obstacle` | `term` | Obstacle description

### DisarmFailed

Disarm callback failed.

Module: `BB.Error.Safety.DisarmFailed`

Fields:

Field | Type | Description
--- | --- | ---
`path` | `[atom]` | Process path
`reason` | `term` | Failure reason

### EmergencyStop

Emergency stop triggered.

Module: `BB.Error.Safety.EmergencyStop`

Fields:

Field | Type | Description
--- | --- | ---
`source` | `term` | What triggered the stop

### LimitExceeded

Joint limit exceeded.

Module: `BB.Error.Safety.LimitExceeded`

Fields:

Field | Type | Description
--- | --- | ---
`joint` | `atom` | Joint name
`limit` | `atom` | `:position`, `:velocity`, or `:effort`
`value` | `float` | Actual value
`max` | `float` | Maximum allowed

## Kinematics Errors

Motion planning failures.

Class: `:kinematics`

### NoDofs

No degrees of freedom available.

Module: `BB.Error.Kinematics.NoDofs`

Fields:

Field | Type | Description
--- | --- | ---
`chain` | `[atom]` | Kinematic chain

Severity: `:error`

### NoSolution

Inverse kinematics found no solution.

Module: `BB.Error.Kinematics.NoSolution`

Fields:

Field | Type | Description
--- | --- | ---
`target` | `Transform` | Requested pose
`reason` | `term` | Why no solution exists

Severity: `:error`

### MultiFailed

Multiple IK attempts failed.

Module: `BB.Error.Kinematics.MultiFailed`

Fields:

Field | Type | Description
--- | --- | ---
`attempts` | `integer` | Number of attempts
`errors` | `[term]` | Individual errors

Severity: `:error`

### SelfCollision

Motion would cause self-collision.

Module: `BB.Error.Kinematics.SelfCollision`

Fields:

Field | Type | Description
--- | --- | ---
`link_a` | `atom` | First colliding link
`link_b` | `atom` | Second colliding link

Severity: `:warning`

### Singularity

Near kinematic singularity.

Module: `BB.Error.Kinematics.Singularity`

Fields:

Field | Type | Description
--- | --- | ---
`joint` | `atom` | Joint near singularity
`manipulability` | `float` | Manipulability measure

Severity: `:warning`

### UnknownLink

Referenced link not found.

Module: `BB.Error.Kinematics.UnknownLink`

Fields:

Field | Type | Description
--- | --- | ---
`link` | `atom` | Unknown link name

Severity: `:error`

### Unreachable

Target is outside workspace.

Module: `BB.Error.Kinematics.Unreachable`

Fields:

Field | Type | Description
--- | --- | ---
`target` | `Transform` | Requested pose
`distance` | `float` | Distance outside workspace

Severity: `:error`

## Invalid Errors

Configuration and validation errors.

Class: `:invalid`

### Command

Invalid command definition.

Module: `BB.Error.Invalid.Command`

Fields:

Field | Type | Description
--- | --- | ---
`command` | `atom` | Command name
`reason` | `term` | Validation failure

Severity: `:error`

### JointConfig

Invalid joint configuration.

Module: `BB.Error.Invalid.JointConfig`

Fields:

Field | Type | Description
--- | --- | ---
`joint` | `atom` | Joint name
`field` | `atom` | Invalid field
`reason` | `term` | Why invalid

Severity: `:error`

### Parameter

Invalid parameter value.

Module: `BB.Error.Invalid.Parameter`

Fields:

Field | Type | Description
--- | --- | ---
`name` | `atom` | Parameter name
`value` | `term` | Invalid value
`expected` | `term` | Expected type/range

Severity: `:error`

### Topology

Invalid topology definition.

Module: `BB.Error.Invalid.Topology`

Fields:

Field | Type | Description
--- | --- | ---
`path` | `[atom]` | Location in topology
`reason` | `term` | Validation failure

Severity: `:error`

## State Errors

State machine violations.

Class: `:state`

### NotAllowed

Command not allowed in current state.

Module: `BB.Error.State.NotAllowed`

Fields:

Field | Type | Description
--- | --- | ---
`current_state` | `atom` | Current robot state
`allowed_states` | `[atom]` | States where command is allowed

Severity: `:error`

### Invalid

Invalid state transition.

Module: `BB.Error.State.Invalid`

Fields:

Field | Type | Description
--- | --- | ---
`from` | `atom` | Current state
`to` | `atom` | Requested state

Severity: `:error`

### Preempted

Command was preempted by another.

Module: `BB.Error.State.Preempted`

Fields:

Field | Type | Description
--- | --- | ---
`command` | `atom` | Original command
`preempted_by` | `atom` | Preempting command

Severity: `:warning`

### Timeout

Command execution timeout.

Module: `BB.Error.State.Timeout`

Fields:

Field | Type | Description
--- | --- | ---
`command` | `atom` | Command that timed out
`elapsed` | `integer` | Time elapsed (ms)

Severity: `:error`

### CommandCrashed

Command process crashed.

Module: `BB.Error.State.CommandCrashed`

Fields:

Field | Type | Description
--- | --- | ---
`command` | `atom` | Command that crashed
`reason` | `term` | Crash reason

Severity: `:error`

## Category Errors

Command category errors.

Class: `:category`

### Full

Command category is at capacity.

Module: `BB.Error.Category.Full`

Fields:

Field | Type | Description
--- | --- | ---
`category` | `atom` | Category name
`capacity` | `integer` | Maximum concurrent commands
`running` | `integer` | Currently running

Severity: `:error`

## Protocol Errors

Low-level protocol failures.

Class: `:protocol`

Used by driver packages (e.g., Robotis Dynamixel protocol errors).

## Creating Errors

Always use `exception/1` to create errors so that Splode can capture backtraces:

    # Create error with exception/1 (captures backtrace)
    error = BB.Error.State.NotAllowed.exception(
      current_state: :disarmed,
      allowed_states: [:idle]
    )

    # Check severity
    BB.Error.Severity.severity(error)  #=> :error

    # Get message
    BB.Error.message(error)  #=> "Command not allowed in state :disarmed..."

Do not create error structs directly - this bypasses Splode's backtrace capture:

    # Avoid - no backtrace captured
    error = %BB.Error.State.NotAllowed{
      current_state: :disarmed,
      allowed_states: [:idle]
    }

## Returning Errors

Prefer structured errors over tuples:

    # Good - use exception/1
    {:error, BB.Error.State.NotAllowed.exception(current_state: :disarmed, allowed_states: [:idle])}

    # Avoid - tuple-based errors
    {:error, {:not_allowed, :disarmed}}

← Previous Page Understanding Safety in Beam Bots
Next Page → Message Types Reference