could not reach the running OpenLogi Agent; start the Agent…

Error message

could not reach the running OpenLogi Agent; start the Agent and retry (semantic profile capture has no direct-hardware fallback)

What it means

Semantic profile capture (`record_profile`) talks to the running OpenLogi Agent over IPC and, unlike `record_case`, has no direct-hardware fallback. `safe_connect_error` maps `ConnectError::Endpoint` — the local-socket endpoint could not be reached — into this actionable error telling the user to start the Agent.

Solutions

Start the OpenLogi Agent (launch the GUI once or the agent binary directly), then retry the command
Check the agent is actually running (`pgrep openlogi-agent`) and not stuck restarting
Enable agent autostart/login launch so it is always up before capture
Verify no dev-mode opt-out (`OPENLOGI_DEV_AGENT=0`) or environment difference is hiding the agent's socket

Example fix

// before (agent not running)
openlogi fixture record-profile ...
// after
openlogi-agent &   # or launch the OpenLogi GUI once
openlogi fixture record-profile ...

Defensive patterns

Strategy: retry

Validate before calling

// probe the agent socket before capture
let endpoint = openlogi_ipc::local_socket_path();
if !endpoint.exists() {
    eprintln!("agent socket not found at {endpoint:?}; start the agent first");
}
if !std::process::Command::new("pgrep")
    .args(["-x", "openlogi-agent"])
    .status().map(|s| s.success()).unwrap_or(false)
{
    eprintln!("openlogi-agent is not running; start it and retry");
}

Try / catch

match connect_to_agent().await {
    Ok(conn) => capture(conn).await,
    Err(e) if e.to_string().contains("could not reach the running OpenLogi Agent") => {
        spawn_agent_or_prompt_user();
        // retry connect once
    }
    Err(e) => return Err(e),
}

Prevention

Enable agent autostart so it is always up before CLI hardware commands
Add a preflight agent liveness check to capture scripts
Quit the GUI cleanly (or use OPENLOGI_DEV_AGENT) in dev loops so the agent is left running intentionally

When it happens

Trigger: `connect_to_agent` is called while no agent process is running (socket doesn't exist), the agent just started and hasn't bound the socket yet, or the socket is stale (agent crashed and left the endpoint behind).

Common situations: Fresh install where the agent/autostart was never enabled; agent quit after an earlier crash; running the CLI in a container/another user session where the agent's socket isn't visible.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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

Appendix: source

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

) -> 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)"
        ),
    }
}

async fn capture_connected(args: RecordProfileArgs, connection: Connection) -> Result<()> {
    let captured =
        capture_connected_profile(&connection, args.device.as_deref(), args.id, args.name).await?;
    let profile = captured.profile;
    super::output::write_json_atomically(&args.output, &profile, args.force, "device profile")?;

    println!(
        "Recorded semantic profile `{}` to {} through the running Agent.",

View on GitHub (pinned to e846e6f4b4)