Errors

Every fallible call returns lager::Result<T>, an alias for std::result::Result<T, lager::Error>.

pub type Result<T> = std::result::Result<T, Error>;

Error is #[non_exhaustive], so a match on it needs a catch-all arm and new variants will not break your build.

Variants

Variant	Fires when
`Connection(String)`	The box is unreachable — DNS, TCP connect, transport failure
`Timeout(String)`	A client-side deadline expired
`Box { status, message }`	The box accepted the request and reported a failure
`DfuFailed { status, exit_code, stdout, stderr }`	Box-side `dfu-util` exited non-zero
`FlashFailed { error, output }`	A debug flash ran but programmed nothing
`ProbeBusy { message }`	Another operation held the debug probe too long
`SafetyRefused { message }`	The net’s safety settings refused a flash or erase
`UnsupportedByBox { message }`	This box’s software is too old for an endpoint that exists
`NotSupportedByBox { feature, details }`	The crate has no route for this at all
`Decode(String)`	The response could not be parsed
`AuthRequired { box_host, auth_url, message }`	A gated box, and no usable credential
`Config(String)`	A client-side configuration problem
`Stream(String)`	A streaming session (UART or RTT) failed

Variant Reference

`Connection(String)`

The crate did not reach the box at all. This variant also covers a failed Socket.IO connect.

cannot reach the Lager box: {msg}. Check network/Tailscale and that the box is
online and updated

`Timeout(String)`

A client-side deadline expired: the HTTP request, a streaming session’s connect confirmation, or a wait_for needle that never arrived.

request to the Lager box timed out: {msg}

A hardware wait that expires is not this variant. wait_for_level timing out on the box comes back as Error::Box with HTTP 502 and GPIO 'gpio24' did not reach level 1 within 2.0s, because the box completed the request and reported the outcome. Error::Timeout means the transport gave up.

`Box { status: u16, message: String }`

The box accepted the request and reported a failure. This is the variant you will see most, and the message is the box’s own text.

box error (HTTP {status}): {message}

Common shapes:

Situation	Status	Message
Net does not exist	404	`[Supply] Net 'x' not found. Create it with 'lager nets add'.`
Net exists, wrong role	404	`Net 'gpio24 (role adc)' not found`
Debug net, wrong role	404	`net 'adc1' exists but is not a debug net`
Debug net missing	404	`debug net 'nosuch' not found on this box`
Setpoint over a hardware limit	400	`Voltage 999.0V exceeds hardware limit 60.0V`
Setpoint over a safety ceiling	502	`Refused voltage(5.0) on net 'supply2': exceeds max_voltage of 3.6`
Box lock held by someone else	409	`Box is locked by <holder>`
Instrument absent from the bus	502	`Could not open instrument at <address>: No device found.`

A router net’s “not found” reads Net 'router1' not found with no role, because router nets deliberately send no role hint. The box can also report failure with HTTP 200 and success: false — a cross-role instrument conflict does this. That is still Error::Box.

`UnsupportedByBox { message }`

The endpoint exists in the API, but this box is too old to serve it. The message names the version needed.

{message}. This box image does not support this endpoint; update the box

Examples:

Call	Needs box
`UsbPort::state()`	0.29.0
`usb_devices()`, `dfu()`	0.33.0
safety limits, interactive RTT	0.35.0
`DebugNet::erase_range()`	0.50.0
`scope()`	0.55.0
`hsm()`, `custom()`	0.59.0
`DebugNet::halt()`, `Arm::get_acceleration()`	0.60.0

erase_range() and halt() check the debug service’s features before they send anything. So an old box fails with this variant before it touches the target.

`NotSupportedByBox { feature, details }`

The crate has no route for this feature on any box. Since crate 0.8, no net type returns it: Scope was the last stub. The variant stays, so a match on it still compiles.

'{feature}' is not yet available over the box HTTP API: {details}

UnsupportedByBox and NotSupportedByBox are different variants with confusingly similar names. Unsupported means update the box. Not supported means no box can do this yet.

`DfuFailed { status, exit_code, stdout, stderr }`

Box-side dfu-util ran and exited non-zero (HTTP 502 from POST /usb/dfu). Both output streams are complete, and the message quotes both. dfu-util reports some device failures on stdout, and its suffix warnings on stderr.

box error (HTTP 502): dfu-util exited with code {exit_code}
stderr:
...
stdout:
...

`FlashFailed { error, output }`

A debug flash ran but programmed nothing. The box answers HTTP 200 with programmed: false for this (box 0.51.0 and later). error is the box’s verdict line, and output is the backend’s output.

flash failed: {error}
output:
...

`ProbeBusy { message }`

Another operation, such as a flash or an erase, held the debug probe for longer than the box waits (HTTP 503 from the debug service). Retry when the other operation is done.

debug probe busy: {message}

`SafetyRefused { message }`

The net is configured with allow_destructive: false, and the debug service refused a flash or an erase (HTTP 403).

refused by the net's safety settings: {message}

`Decode(String)`

The crate did not parse the response into the expected shape. The cause is a truncated body, an unexpected field type, or a missing required field.

could not decode box response: {msg}

`AuthRequired { box_host, auth_url, message }`

A gated box, and no usable credential.

{message}. Sign in with `lager login {auth_url}` (this crate reuses the CLI's
session), or set LAGER_GATEWAY_TOKEN / use LagerBoxBuilder::bearer_token

See Authentication.

`Config(String)`

A client-side problem, detected before anything is sent: LAGER_BOX_HOST unset, an unparseable host, a firmware path whose type cannot be inferred, an unreadable file.

configuration error: {msg}

`Stream(String)`

A UART or RTT session failed: the net is already in use by another session, the device disappeared, or the session closed unexpectedly.

streaming session error: {msg}

Matching

use lager::Error;

match supply.set_voltage(5.0) {
    Ok(()) => {}
    Err(Error::UnsupportedByBox { message }) => {
        eprintln!("box too old, skipping: {message}");
        return Ok(());
    }
    Err(Error::Box { status: 502, message }) => {
        panic!("refused by a safety limit: {message}");
    }
    Err(Error::AuthRequired { auth_url, .. }) => {
        panic!("run `lager login {auth_url}` first");
    }
    Err(e) => return Err(e),   // Error is #[non_exhaustive]
}

Skipping a test on an old box

fn skip_if_unsupported<T>(r: lager::Result<T>) -> Option<T> {
    match r {
        Ok(v) => Some(v),
        Err(lager::Error::UnsupportedByBox { message }) => {
            eprintln!("skipping: {message}");
            None
        }
        Err(e) => panic!("{e}"),
    }
}

Notes

Error implements std::error::Error and Display, so ? works into Box<dyn Error> and anyhow::Error without a conversion.
From<serde_json::Error> maps into Error::Decode.
The messages are written to be read by a person in CI output. Print the error rather than only its variant.

Getting Started

Development

Power & Simulation

Measurement

I/O & Communication

Utilities

Security

Guides

Variants

Variant Reference

`Connection(String)`

`Timeout(String)`

`Box { status: u16, message: String }`

`UnsupportedByBox { message }`

`NotSupportedByBox { feature, details }`

`DfuFailed { status, exit_code, stdout, stderr }`

`FlashFailed { error, output }`

`ProbeBusy { message }`

`SafetyRefused { message }`

`Decode(String)`

`AuthRequired { box_host, auth_url, message }`

`Config(String)`

`Stream(String)`

Matching

Skipping a test on an old box

Notes

​Variants

​Variant Reference

​Connection(String)

​Timeout(String)

​Box { status: u16, message: String }

​UnsupportedByBox { message }

​NotSupportedByBox { feature, details }

​DfuFailed { status, exit_code, stdout, stderr }

​FlashFailed { error, output }

​ProbeBusy { message }

​SafetyRefused { message }

​Decode(String)

​AuthRequired { box_host, auth_url, message }

​Config(String)

​Stream(String)

​Matching

​Skipping a test on an old box

​Notes

Variants

Variant Reference

`Connection(String)`

`Timeout(String)`

`Box { status: u16, message: String }`

`UnsupportedByBox { message }`

`NotSupportedByBox { feature, details }`

`DfuFailed { status, exit_code, stdout, stderr }`

`FlashFailed { error, output }`

`ProbeBusy { message }`

`SafetyRefused { message }`

`Decode(String)`

`AuthRequired { box_host, auth_url, message }`

`Config(String)`

`Stream(String)`

Matching

Skipping a test on an old box

Notes