Search documentation of snmpkit

# SnmpKit.SnmpLib.Error (snmpkit v1.3.17)

Standard SNMP error handling and error code utilities.

Provides standardized error codes, error handling utilities, and error response generation for SNMP operations. This module centralizes all SNMP-specific error handling to ensure consistent error reporting across the library.

## SNMP Error Codes

Standard SNMP error status values as defined in RFC 1157 and RFC 3416:

- `no_error` (0) - No error occurred
- `too_big` (1) - Response message would be too large
- `no_such_name` (2) - Requested OID does not exist
- `bad_value` (3) - Invalid value for SET operation
- `read_only` (4) - Attempted to set read-only variable
- `gen_err` (5) - General error

## Usage Examples

### Basic Error Handling

    # Check if an error is retriable
    if SnmpKit.SnmpLib.Error.retriable_error?(error_code) do
      retry_operation()
    end

    # Format error for logging
    error_msg = SnmpKit.SnmpLib.Error.format_error(3, 2, varbinds)
    Logger.error(error_msg)

### Error Response Generation

    # Create error response for invalid request
    {:ok, error_response} = SnmpKit.SnmpLib.Error.create_error_response(
      request_pdu,
      :no_such_name,
      error_index
    )

# Summary

## Types

error_index()
error_status()
varbind()
varbinds()

## Functions

all_error_atoms()

Returns a list of all standard SNMP error atoms.

all_error_codes()

Returns a list of all standard SNMP error codes.

bad_value()

Returns the numeric code for 'bad value' error status.

create_error_response(request_pdu, error_status, error_index)

Creates an SNMP error response PDU.

error_atom(code)

Converts error status code to atom representation.

error_code(name)

Converts error atom or name to numeric code.

error_name(arg1)

Returns the human-readable name for an error status code.

error_severity(error_status)

Categorizes error by severity level.

format_error(error_status, error_index, varbinds \\ [])

Formats an SNMP error for human-readable display.

gen_err()

Returns the numeric code for 'general error' status.

no_error()

Returns the numeric code for 'no error' status.

no_such_name()

Returns the numeric code for 'no such name' error status.

read_only()

Returns the numeric code for 'read only' error status.

retriable_error?(error_status)

Determines if an error status indicates a retriable condition.

too_big()

Returns the numeric code for 'too big' error status.

valid_error_status?(status)

Validates an error status code.

# Types

# error_index()

    @type error_index() :: non_neg_integer()

# error_status()

    @type error_status() ::
      :no_error
      | :too_big
      | :no_such_name
      | :bad_value
      | :read_only
      | :gen_err
      | non_neg_integer()

# varbind()

    @type varbind() :: {list(), any()}

# varbinds()

    @type varbinds() :: [varbind()]

# Functions

# all_error_atoms()

    @spec all_error_atoms() :: [
      :no_error
      | :too_big
      | :no_such_name
      | :bad_value
      | :read_only
      | :gen_err
      | :no_access
      | :wrong_type
      | :wrong_length
      | :wrong_encoding
      | :wrong_value
      | :no_creation
      | :inconsistent_value
      | :resource_unavailable
      | :commit_failed
      | :undo_failed
      | :authorization_error
      | :not_writable
      | :inconsistent_name
    ]

Returns a list of all standard SNMP error atoms.

## Examples

    iex> atoms = SnmpKit.SnmpLib.Error.all_error_atoms()
    iex> :no_error in atoms
    true
    iex> :gen_err in atoms
    true

# all_error_codes()

    @spec all_error_codes() :: [non_neg_integer()]

Returns a list of all standard SNMP error codes.

## Examples

    iex> codes = SnmpKit.SnmpLib.Error.all_error_codes()
    iex> 0 in codes
    true
    iex> 5 in codes
    true

# bad_value()

    @spec bad_value() :: 3

Returns the numeric code for 'bad value' error status.

The value provided in a SET operation is invalid for the variable.

## Examples

    iex> SnmpKit.SnmpLib.Error.bad_value()
    3

# create_error_response(request_pdu, error_status, error_index)

    @spec create_error_response(map(), error_status(), error_index()) ::
      {:ok, map()} | {:error, atom()}

Creates an SNMP error response PDU.

Generates a properly formatted error response based on the original request and the error condition that occurred.

## Parameters

- `request_pdu`: Original request PDU
- `error_status`: Error status code or atom
- `error_index`: Index of the varbind that caused the error (1-based)

## Returns

- `{:ok, error_pdu}`: Successfully created error response
- `{:error, reason}`: Failed to create error response

## Examples

    request = %{type: :get_request, request_id: 123, varbinds: [...]}
    {:ok, error_response} = SnmpKit.SnmpLib.Error.create_error_response(
      request,
      :no_such_name,
      1
    )

# error_atom(code)

    @spec error_atom(error_status()) :: atom()

Converts error status code to atom representation.

## Examples

    iex> SnmpKit.SnmpLib.Error.error_atom(2)
    :no_such_name

    iex> SnmpKit.SnmpLib.Error.error_atom(999)
    :unknown_error

# error_code(name)

    @spec error_code(atom() | String.t()) :: non_neg_integer()

Converts error atom or name to numeric code.

## Examples

    iex> SnmpKit.SnmpLib.Error.error_code(:no_such_name)
    2

    iex> SnmpKit.SnmpLib.Error.error_code("bad_value")
    3

# error_name(arg1)

    @spec error_name(error_status()) :: String.t()

Returns the human-readable name for an error status code.

## Parameters

- `code`: Numeric error status code or atom

## Returns

- String name of the error status
- "unknown_error" for unrecognized codes

## Examples

    iex> SnmpKit.SnmpLib.Error.error_name(0)
    "no_error"

    iex> SnmpKit.SnmpLib.Error.error_name(:too_big)
    "too_big"

    iex> SnmpKit.SnmpLib.Error.error_name(999)
    "unknown_error"

# error_severity(error_status)

    @spec error_severity(error_status()) :: :info | :warning | :error

Categorizes error by severity level.

## Returns

- `:info` - No error
- `:warning` - Retriable errors
- `:error` - Non-retriable errors

## Examples

    iex> SnmpKit.SnmpLib.Error.error_severity(:no_error)
    :info

    iex> SnmpKit.SnmpLib.Error.error_severity(:too_big)
    :warning

    iex> SnmpKit.SnmpLib.Error.error_severity(:no_such_name)
    :error

# format_error(error_status, error_index, varbinds \\ [])

    @spec format_error(error_status(), error_index(), varbinds()) :: String.t()

Formats an SNMP error for human-readable display.

## Parameters

- `error_status`: Error status code (integer or atom)
- `error_index`: Index of the varbind that caused the error (1-based)
- `varbinds`: List of varbinds from the request (optional)

## Returns

Formatted error string suitable for logging or display.

## Examples

    iex> SnmpKit.SnmpLib.Error.format_error(2, 1, [])
    "SNMP Error: no_such_name (2) at index 1"

    iex> varbinds = [{[1,3,6,1,2,1,1,1,0], "test"}]
    iex> SnmpKit.SnmpLib.Error.format_error(:bad_value, 1, varbinds)
    "SNMP Error: bad_value (3) at index 1 - OID: 1.3.6.1.2.1.1.1.0"

# gen_err()

    @spec gen_err() :: 5

Returns the numeric code for 'general error' status.

A general error occurred that doesn't fit other categories.

## Examples

    iex> SnmpKit.SnmpLib.Error.gen_err()
    5

# no_error()

    @spec no_error() :: 0

Returns the numeric code for 'no error' status.

## Examples

    iex> SnmpKit.SnmpLib.Error.no_error()
    0

# no_such_name()

    @spec no_such_name() :: 2

Returns the numeric code for 'no such name' error status.

The requested OID does not exist on the agent.

## Examples

    iex> SnmpKit.SnmpLib.Error.no_such_name()
    2

# read_only()

    @spec read_only() :: 4

Returns the numeric code for 'read only' error status.

Attempted to set a read-only variable.

## Examples

    iex> SnmpKit.SnmpLib.Error.read_only()
    4

# retriable_error?(error_status)

    @spec retriable_error?(error_status()) :: boolean()

Determines if an error status indicates a retriable condition.

Some SNMP errors are temporary and operations can be retried, while others indicate permanent failures.

## Retriable Errors

- `too_big` - Can retry with smaller request
- `gen_err` - General error, may be temporary
- `resource_unavailable` - Temporary resource constraint

## Non-Retriable Errors

- `no_such_name` - OID doesn't exist
- `bad_value` - Invalid value provided
- `read_only` - Attempted to write read-only variable
- `no_access` - Access denied
- Most SNMPv2c specific errors

## Examples

    iex> SnmpKit.SnmpLib.Error.retriable_error?(:too_big)
    true

    iex> SnmpKit.SnmpLib.Error.retriable_error?(:no_such_name)
    false

# too_big()

    @spec too_big() :: 1

Returns the numeric code for 'too big' error status.

The response message would be too large to fit in a single SNMP message.

## Examples

    iex> SnmpKit.SnmpLib.Error.too_big()
    1

# valid_error_status?(status)

    @spec valid_error_status?(any()) :: boolean()

Validates an error status code.

## Examples

    iex> SnmpKit.SnmpLib.Error.valid_error_status?(2)
    true

    iex> SnmpKit.SnmpLib.Error.valid_error_status?(:no_such_name)
    true

    iex> SnmpKit.SnmpLib.Error.valid_error_status?(999)
    false