Module error 

Error types for async-snmp.

This module provides comprehensive error handling for SNMP operations, including:

• Error - The main error type for all library operations
• ErrorStatus - SNMP protocol errors returned by agents (RFC 3416)
• Helper types for authentication, encryption, and encoding errors

All errors are #[non_exhaustive] to allow adding new variants without breaking changes.

Error Handling Patterns

Basic Error Matching

Most applications should match on specific error variants to provide appropriate responses:

use async_snmp::{Auth, Client, Error, ErrorStatus, oid};

let client = Client::builder("192.168.1.1:161", Auth::v2c("public"))
    .connect()
    .await?;

match client.get(&oid!(1, 3, 6, 1, 2, 1, 1, 1, 0)).await {
    Ok(varbind) => {
        println!("Value: {:?}", varbind.value);
    }
    Err(Error::Timeout { elapsed, retries, .. }) => {
        println!("Request timed out after {:?} ({} retries)", elapsed, retries);
    }
    Err(Error::Snmp { status, index, .. }) => {
        println!("SNMP error: {} at index {}", status, index);
    }
    Err(e) => {
        println!("Other error: {}", e);
    }
}

SNMP Protocol Errors

ErrorStatus represents errors returned by SNMP agents. Common cases include:

use async_snmp::{Auth, Client, Error, ErrorStatus, Value, oid};

let client = Client::builder("192.168.1.1:161", Auth::v2c("private"))
    .connect()
    .await?;

let result = client.set(&oid!(1, 3, 6, 1, 2, 1, 1, 4, 0), Value::from("admin@example.com")).await;

if let Err(Error::Snmp { status, oid, .. }) = result {
    match status {
        ErrorStatus::NoSuchName => {
            println!("OID does not exist");
        }
        ErrorStatus::NotWritable => {
            println!("Object is read-only");
        }
        ErrorStatus::AuthorizationError => {
            println!("Access denied - check community string");
        }
        ErrorStatus::WrongType | ErrorStatus::WrongValue => {
            println!("Invalid value for this OID");
        }
        _ => {
            println!("SNMP error: {}", status);
        }
    }
    if let Some(oid) = oid {
        println!("Problematic OID: {}", oid);
    }
}

Timeout Handling

Timeouts include retry information to help diagnose connectivity issues:

use async_snmp::{Auth, Client, Error, Retry, oid};
use std::time::Duration;

let client = Client::builder("192.168.1.1:161", Auth::v2c("public"))
    .timeout(Duration::from_secs(2))
    .retry(Retry::fixed(3, Duration::ZERO))
    .connect()
    .await
    .expect("failed to create client");

match client.get(&oid!(1, 3, 6, 1, 2, 1, 1, 1, 0)).await {
    Err(Error::Timeout { target, elapsed, request_id, retries }) => {
        if let Some(addr) = target {
            println!("No response from {} after {:?}", addr, elapsed);
        }
        println!("Request ID {} failed after {} retries", request_id, retries);
        // Consider: is the host reachable? Is SNMP enabled? Is the port correct?
    }
    _ => {}
}

SNMPv3 Errors

SNMPv3 operations can fail with authentication or encryption errors:

use async_snmp::{Auth, AuthProtocol, Client, Error, AuthErrorKind, oid};

let client = Client::builder(
    "192.168.1.1:161",
    Auth::usm("admin").auth(AuthProtocol::Sha256, "wrongpassword"),
)
.connect()
.await
.expect("failed to create client");

match client.get(&oid!(1, 3, 6, 1, 2, 1, 1, 1, 0)).await {
    Err(Error::AuthenticationFailed { kind, .. }) => {
        match kind {
            AuthErrorKind::HmacMismatch => {
                println!("Wrong password or credentials");
            }
            AuthErrorKind::NoUser => {
                println!("User not configured on agent");
            }
            _ => {
                println!("Auth failed: {}", kind);
            }
        }
    }
    Err(Error::NotInTimeWindow { .. }) => {
        println!("Clock skew between client and agent");
    }
    Err(Error::UnknownEngineId { .. }) => {
        println!("Engine discovery failed");
    }
    _ => {}
}

Enums

AuthErrorKind

Authentication error kinds (SNMPv3).

CryptoErrorKind

Cryptographic error kinds (encryption/decryption).

DecodeErrorKind

BER decode error kinds.

EncodeErrorKind

BER encode error kinds.

Error

The main error type for all async-snmp operations.

ErrorStatus

SNMP protocol error status codes (RFC 3416).

OidErrorKind

OID validation error kinds.

Type Aliases

Result

Result type alias using the library’s Error type.