a retained Agent inventory route is not safely addressable

Error message

a retained Agent inventory route is not safely addressable

What it means

Raised in `capture_inventory` when `DeviceRoute::device_route_for(&retained, device.slot)` returns `None` for any device in the retained (pre-sanitization) inventory's `paired` list. Every retained device must be safely addressable on the HID++ route so its settings can be read; an unaddressable route means the inventory data is internally inconsistent (e.g. slot has no resolving route in the receiver/standalone structure).

Solutions

Restart the agent to refresh its device inventory and retry the capture.
Confirm all devices finish pairing before recording (no devices mid-enumeration).
Check agent/CLI protocol version match (the CLI already bails on mismatch earlier, but an older running agent binary can emit odd slot data).
If reproducible with a specific device, capture `openlogi list` output and file a bug with the inventory shape.

Defensive patterns

Strategy: validation

Validate before calling

// pre-check every paired device resolves a route before capture
for d in &inventory.paired {
    assert!(DeviceRoute::device_route_for(&inventory, d.slot).is_some(), "unaddressable slot {}", d.slot);
}

Prevention

Restart the agent if inventory slot data looks inconsistent.
Avoid recording profiles while devices are mid-pairing.
Keep agent and CLI on the same release so route semantics match.

When it happens

Trigger: `capture_inventory` iterates `retained.paired` and builds routes; `device_route_for` fails for a device whose slot cannot be mapped to a route — typically a slot value inconsistent with the inventory's receiver/pairing metadata in the Agent snapshot.

Common situations: An agent snapshot with corrupt or transitional pairing state (device mid-pairing); a device record whose slot references a nonexistent receiver container; snapshot produced by an agent version with different route semantics.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of AprilNEA/OpenLogi@e846e6f4b4 (2026-09-13). Data as JSON: /api/errors/c7e8e6fcbfec6747. Report an issue: GitHub.

Appendix: source

Thrown at crates/openlogi-cli/src/cmd/fixture/record_profile.rs:236

async fn capture_inventory(
    client: &AgentClient,
    source: &DeviceInventory,
    selected_device: usize,
) -> Result<ProfileCaptureParts> {
    let mut retained = source.clone();
    if retained.receiver.unique_id.is_none() {
        retained.paired = vec![source.paired.get(selected_device).cloned().ok_or_else(|| {
            anyhow!("the selected direct device is absent from the Agent snapshot")
        })?];
    }

    let source_routes = retained
        .paired
        .iter()
        .map(|device| {
            DeviceRoute::device_route_for(&retained, device.slot).ok_or_else(|| {
                anyhow!("a retained Agent inventory route is not safely addressable")
            })
        })
        .collect::<Result<Vec<_>>>()?;
    let retained_selected = if retained.receiver.unique_id.is_none() {
        0
    } else {
        selected_device
    };
    sanitize::inventory(&mut retained)?;
    let profile_routes = retained
        .paired
        .iter()
        .map(|device| {
            DeviceRoute::device_route_for(&retained, device.slot)
                .ok_or_else(|| anyhow!("a sanitized profile route is not addressable"))
        })
        .collect::<Result<Vec<_>>>()?;
    let selected_route = profile_routes

View on GitHub (pinned to e846e6f4b4)