a retained offline HID++ route has no captured

Error message

a retained offline HID++ route has no captured {family} capability fact; refusing to guess support (no profile was written)

What it means

Raised by `unknown_offline_support` when a retained device is offline and a required capability fact (SmartShift or backlight) is missing, so its support level cannot be recorded. For online devices the CLI performs a live semantic read; offline devices have no fallback, and the CLI deliberately refuses to guess support, aborting the capture so no profile is written.

Solutions

Wake the device (move/click the mouse, press a key) so the agent reports it online, then re-run the capture.
Toggle the device's power switch off/on and let the agent reconnect before recording.
Re-pair or move the device closer to the receiver if it cannot stay connected.
Record the profile while the device is actively connected — offline devices cannot complete semantic reads by design.

Example fix

// before: device asleep, capture aborts
openlogi fixture record profile --id mx --name "MX" --output mx.json
// after: wake the device first (click/scroll), confirm online, then
openlogi list
openlogi fixture record profile --id mx --name "MX" --output mx.json

Defensive patterns

Strategy: validation

Validate before calling

// pre-check: only record when every targeted device is online
let all_online = snapshot.inventory.iter().flat_map(|i| &i.paired).all(|d| d.online);
if !all_online { eprintln!("wake all devices before recording"); }

Type guard

fn is_online(d: &PairedDevice) -> bool { d.online }

Prevention

Wake and actively use the device just before recording.
Confirm `openlogi list` shows the device online.
Replace batteries / move closer to the receiver if it keeps dropping offline.

When it happens

Trigger: Recording a profile where `device.online == false` and either `capabilities.hires_wheel`-style facts are absent (leading `capability_setting` to return `None` paths for offline) or — as coded — SmartShift/backlight are needed while the device is offline: SmartShift always requires an online read; backlight requires one unless RGB capability proves backlight unsupported.

Common situations: User selects a mouse/keyboard that is asleep, powered off, or out of wireless range; device in a powered-off state after the agent cached stale capability data; trying to record a profile for a docked device that has gone to sleep.

Related errors

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

Appendix: source

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

        wheel,
        backlight,
        lighting: profile_support(capabilities.lighting),
        light: ProfileSupport::Unsupported,
    })
}

fn capability_setting<T>(online: bool, supported: bool) -> Option<ProfileSetting<T>> {
    if !supported {
        Some(ProfileSetting::Unsupported)
    } else if online {
        None
    } else {
        Some(ProfileSetting::Unavailable)
    }
}

fn unknown_offline_support(family: &str) -> anyhow::Error {
    anyhow!(
        "a retained offline HID++ route has no captured {family} capability fact; refusing to \
         guess support (no profile was written)"
    )
}

async fn semantic_read<T>(
    family: &'static str,
    request: impl Future<Output = Result<Result<T, WriteError>, RpcError>>,
) -> Result<ProfileSetting<T>> {
    let result = tokio::time::timeout(READ_TIMEOUT, request)
        .await
        .map_err(|_| safe_read_error(family))?
        .map_err(|_| safe_read_error(family))?;
    match result {
        Ok(value) => Ok(ProfileSetting::Supported(value)),
        Err(WriteError::FeatureUnsupported { .. }) => Ok(ProfileSetting::Unsupported),
        Err(_) => Err(safe_read_error(family)),
    }

View on GitHub (pinned to e846e6f4b4)