timed out connecting to the running OpenLogi Agent…

Error message

timed out connecting to the running OpenLogi Agent; semantic profile capture requires a responsive Agent and will not access hardware directly

What it means

Semantic profile capture (`record_profile`) refuses to talk to hardware directly; it requires the running OpenLogi Agent over IPC. `connect_to_agent` wraps the tarpc connect in a timeout, and this error is raised when the connection does not complete within CONNECT_TIMEOUT. It is a deliberate safety policy: capture must never bypass the agent and access HID devices itself.

Solutions

Start the OpenLogi agent (or launch the OpenLogi app, which starts it) and retry the command
Check for a hung agent process (e.g. stuck on the singleton lock) and kill/restart it
Verify the dev environment: with OPENLOGI_DEV_AGENT set, the CLI expects the dev IPC socket — use the agent-mock or unset the override as appropriate
Rebuild/reinstall so the CLI and agent are from the same bundle and use the same socket path

Example fix

// before
$ openlogi fixture record-profile --id syn-1   # agent not running
error: timed out connecting to the running OpenLogi Agent; ...
// after
$ openlogi-agent &          # or launch the OpenLogi app
$ openlogi fixture record-profile --id syn-1

Defensive patterns

Strategy: retry

Validate before calling

// shell pre-check before running the CLI
if ! pgrep -x openlogi-agent >/dev/null; then echo "agent not running; start OpenLogi first"; fi

Try / catch

match result {
    Err(e) if e.to_string().contains("timed out connecting to the running OpenLogi Agent") => {
        start_or_restart_agent();
        retry_with_backoff(connect_to_agent, 3);
    }
    other => other,
}

Prevention

Launch the OpenLogi app (or openlogi-agent) before fixture commands in scripts
Add a health/ readiness wait on the agent socket before invoking capture
In dev, use OPENLOGI_DEV_AGENT=0 intentionally and know which socket you target
Use the agent-mock (openlogi-agent-mock) when no hardware/agent is available

When it happens

Trigger: Running `openlogi fixture record-profile` (via `run`/`capture_for_contribution`) when the agent is not running, is hung, or its IPC socket is unreachable, so `client::connect()` does not resolve within CONNECT_TIMEOUT.

Common situations: The agent process was quit or crashed; a stale agent is stuck on a singleton lock; the user runs the CLI before launching the GUI/agent; the agent is an old build listening on a different socket version.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

Appendix: source

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

type ProfileCaptureParts = (
    Vec<DeviceInventory>,
    Vec<StandaloneDevice>,
    Vec<ProfileDeviceSettings>,
    DeviceRoute,
);

pub(super) async fn capture_for_contribution(
    id: String,
    name: String,
    selector: Option<&str>,
) -> Result<CapturedProfile> {
    let connection = connect_to_agent().await?;
    capture_connected_profile(&connection, selector, id, name).await
}

async fn connect_to_agent() -> Result<Connection> {
    match tokio::time::timeout(CONNECT_TIMEOUT, client::connect()).await {
        Err(_) => bail!(
            "timed out connecting to the running OpenLogi Agent; semantic profile capture \
             requires a responsive Agent and will not access hardware directly"
        ),
        Ok(Err(error)) => Err(safe_connect_error(&error)),
        Ok(Ok(connection)) => Ok(connection),
    }
}

fn safe_connect_error(error: &ConnectError) -> anyhow::Error {
    match error {
        ConnectError::Endpoint(_) => anyhow!(
            "could not reach the running OpenLogi Agent; start the Agent and retry (semantic \
             profile capture has no direct-hardware fallback)"
        ),
        ConnectError::Handshake(_) => anyhow!(
            "the running OpenLogi Agent did not complete a healthy IPC handshake; restart it and \
             retry (no profile was written)"
        ),

View on GitHub (pinned to e846e6f4b4)