the running OpenLogi Agent did not complete a healthy IPC…

Error message

the running OpenLogi Agent did not complete a healthy IPC handshake; restart it and retry (no profile was written)

What it means

The sibling of the endpoint error in `safe_connect_error`: the CLI connected to the agent's socket, but the tarpc IPC handshake did not complete healthily. Profile capture aborts before writing anything, so the message reassures that no profile was written.

Solutions

Restart the agent so it matches the CLI's IPC protocol version
Kill any stale agent process (`pkill openlogi-agent`) and relaunch a freshly built/installed one
Rebuild both CLI and agent from the same source tree/commit
Check `PROTOCOL_VERSION` compatibility — bump wire version on both sides if types changed

Example fix

// before: mismatched versions
pkill openlogi-agent
cargo build -p openlogi-agent -p openlogi-cli   # same tree
openlogi-agent &
openlogi fixture record-profile ...

Defensive patterns

Strategy: validation

Validate before calling

// ensure CLI and agent come from the same build
let cli_v = env!("CARGO_PKG_VERSION");
let agent_v = agent_reported_version(); // e.g. via `openlogi --version` of the installed agent
if cli_v != agent_v {
    eprintln!("version skew: cli {cli_v} vs agent {agent_v}; rebuild/restart both");
}

Try / catch

match connect_to_agent().await {
    Ok(conn) => capture(conn).await,
    Err(e) if e.to_string().contains("did not complete a healthy IPC handshake") => {
        restart_agent(); // kill stale process, relaunch same build
    }
    Err(e) => return Err(e),
}

Prevention

Always restart the agent after rebuilding the workspace — never mix dev CLI with installed agent
Bump PROTOCOL_VERSION and retest wire_format when IPC types change
Run GUI and CLI from the same source tree in development

When it happens

Trigger: `connect_to_agent` gets `ConnectError::Handshake` — the agent accepted the connection but failed the versioned handshake, typically because CLI and agent were built from different versions with a mismatched `PROTOCOL_VERSION`, or the agent is unhealthy/mid-restart.

Common situations: Upgrading the CLI but a stale agent from an older build is still running; mixing a dev-built CLI with an installed release agent; agent wedged after a crash while still holding the socket.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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

Appendix: source

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

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.",
        profile.id,
        args.output.display()
    );
    println!(

View on GitHub (pinned to e846e6f4b4)