{"record":{"id":"6290d08b2365d8ff","repo":"AprilNEA/OpenLogi","slug":"could-not-reach-the-running-openlogi-agent-start-the-agent","errorCode":null,"errorMessage":"could not reach the running OpenLogi Agent; start the Agent and retry (semantic profile capture has no direct-hardware fallback)","messagePattern":"could not reach the running OpenLogi Agent; start the Agent and retry \\(semantic profile capture has no direct-hardware fallback\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/openlogi-cli/src/cmd/fixture/record_profile.rs","lineNumber":92,"sourceCode":") -> Result<CapturedProfile> {\n    let connection = connect_to_agent().await?;\n    capture_connected_profile(&connection, selector, id, name).await\n}\n\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.\",","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/AprilNEA/OpenLogi/blob/e846e6f4b4405e33bd6a9aaf949a482ce34cb6d8/crates/openlogi-cli/src/cmd/fixture/record_profile.rs#L74-L110","documentation":"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.","triggerScenarios":"`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).","commonSituations":"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.","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"],"exampleFix":"// before (agent not running)\nopenlogi fixture record-profile ...\n// after\nopenlogi-agent &   # or launch the OpenLogi GUI once\nopenlogi fixture record-profile ...","handlingStrategy":"retry","validationCode":"// probe the agent socket before capture\nlet endpoint = openlogi_ipc::local_socket_path();\nif !endpoint.exists() {\n    eprintln!(\"agent socket not found at {endpoint:?}; start the agent first\");\n}\nif !std::process::Command::new(\"pgrep\")\n    .args([\"-x\", \"openlogi-agent\"])\n    .status().map(|s| s.success()).unwrap_or(false)\n{\n    eprintln!(\"openlogi-agent is not running; start it and retry\");\n}","typeGuard":null,"tryCatchPattern":"match connect_to_agent().await {\n    Ok(conn) => capture(conn).await,\n    Err(e) if e.to_string().contains(\"could not reach the running OpenLogi Agent\") => {\n        spawn_agent_or_prompt_user();\n        // retry connect once\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["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"],"tags":["cli","ipc","agent","connection"],"backgroundTag":"connection-refused","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"}