{"record":{"id":"8610e1bafab9c27c","repo":"AprilNEA/OpenLogi","slug":"the-running-openlogi-agent-did-not-complete-a-healthy-ipc","errorCode":null,"errorMessage":"the running OpenLogi Agent did not complete a healthy IPC handshake; restart it and retry (no profile was written)","messagePattern":"the running OpenLogi Agent did not complete a healthy IPC handshake; restart it and retry \\(no profile was written\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/openlogi-cli/src/cmd/fixture/record_profile.rs","lineNumber":96,"sourceCode":"\nasync fn connect_to_agent() -> Result<Connection> {\n    match tokio::time::timeout(CONNECT_TIMEOUT, client::connect()).await {\n        Err(_) => bail!(\n            \"timed out connecting to the running OpenLogi Agent; semantic profile capture \\\n             requires a responsive Agent and will not access hardware directly\"\n        ),\n        Ok(Err(error)) => Err(safe_connect_error(&error)),\n        Ok(Ok(connection)) => Ok(connection),\n    }\n}\n\nfn safe_connect_error(error: &ConnectError) -> anyhow::Error {\n    match error {\n        ConnectError::Endpoint(_) => anyhow!(\n            \"could not reach the running OpenLogi Agent; start the Agent and retry (semantic \\\n             profile capture has no direct-hardware fallback)\"\n        ),\n        ConnectError::Handshake(_) => anyhow!(\n            \"the running OpenLogi Agent did not complete a healthy IPC handshake; restart it and \\\n             retry (no profile was written)\"\n        ),\n    }\n}\n\nasync fn capture_connected(args: RecordProfileArgs, connection: Connection) -> Result<()> {\n    let captured =\n        capture_connected_profile(&connection, args.device.as_deref(), args.id, args.name).await?;\n    let profile = captured.profile;\n    super::output::write_json_atomically(&args.output, &profile, args.force, \"device profile\")?;\n\n    println!(\n        \"Recorded semantic profile `{}` to {} through the running Agent.\",\n        profile.id,\n        args.output.display()\n    );\n    println!(","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/AprilNEA/OpenLogi/blob/e846e6f4b4405e33bd6a9aaf949a482ce34cb6d8/crates/openlogi-cli/src/cmd/fixture/record_profile.rs#L78-L114","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","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"],"exampleFix":"// before: mismatched versions\npkill openlogi-agent\ncargo build -p openlogi-agent -p openlogi-cli   # same tree\nopenlogi-agent &\nopenlogi fixture record-profile ...","handlingStrategy":"validation","validationCode":"// ensure CLI and agent come from the same build\nlet cli_v = env!(\"CARGO_PKG_VERSION\");\nlet agent_v = agent_reported_version(); // e.g. via `openlogi --version` of the installed agent\nif cli_v != agent_v {\n    eprintln!(\"version skew: cli {cli_v} vs agent {agent_v}; rebuild/restart both\");\n}","typeGuard":null,"tryCatchPattern":"match connect_to_agent().await {\n    Ok(conn) => capture(conn).await,\n    Err(e) if e.to_string().contains(\"did not complete a healthy IPC handshake\") => {\n        restart_agent(); // kill stale process, relaunch same build\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["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"],"tags":["cli","ipc","agent","handshake","versioning"],"backgroundTag":"unexpected-response-shape","analyzedSha":"e846e6f4b4405e33bd6a9aaf949a482ce34cb6d8","analyzedAt":"2026-09-13T03:07:16.451Z","contentChangedAt":"2026-09-13T03:07:16.451Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}