{"record":{"id":"aaf8dadda86c7e65","repo":"nikivdev/code","slug":"launchctl-kickstart-failed","errorCode":null,"errorMessage":"launchctl kickstart failed: {}","messagePattern":"launchctl kickstart failed: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"src/supervisor.rs","lineNumber":584,"sourceCode":"    let output = Command::new(\"launchctl\")\n        .args([\"bootstrap\", &domain, plist_path.to_string_lossy().as_ref()])\n        .output()\n        .context(\"failed to bootstrap launch agent\")?;\n    if !output.status.success() {\n        bail!(\n            \"launchctl bootstrap failed: {}\",\n            String::from_utf8_lossy(&output.stderr)\n        );\n    }\n\n    let _ = Command::new(\"launchctl\").args([\"enable\", &target]).output();\n\n    let output = Command::new(\"launchctl\")\n        .args([\"kickstart\", \"-k\", &target])\n        .output()\n        .context(\"failed to kickstart launch agent\")?;\n    if !output.status.success() {\n        bail!(\n            \"launchctl kickstart failed: {}\",\n            String::from_utf8_lossy(&output.stderr)\n        );\n    }\n\n    println!(\n        \"Installed launch agent {} at {}\",\n        launch_agent_label(),\n        plist_path.display()\n    );\n    Ok(())\n}\n\n#[cfg(target_os = \"macos\")]\nfn launch_agent_kickstart() -> Result<()> {\n    let target = launch_agent_target();\n    let output = Command::new(\"launchctl\")\n        .args([\"kickstart\", \"-k\", &target])","sourceCodeStart":566,"sourceCodeEnd":602,"githubUrl":"https://github.com/nikivdev/code/blob/a747e741ae92c09071d0ae946ab48488adcff1ce/src/supervisor.rs#L566-L602","documentation":"As the final step of install_launch_agent, the code runs `launchctl kickstart -k <target>` to (re)start the freshly bootstrapped launch agent. Non-zero exit from launchctl produces this error with launchctl's stderr. The service label/target was registered but couldn't be started.","triggerScenarios":"install_launch_agent on macOS where bootstrap succeeded but kickstart -k fails — usually a bad label in the plist, the plist's program path missing/not executable, or the service immediately exiting so launchctl reports failure.","commonSituations":"Plist points to a binary path that doesn't exist or lacks +x; mismatch between the kickstart target label and the plist's Label key; launchd job crashes at startup (bad config); macOS permission prompt not granted.","solutions":["Check the stderr in this error and run `launchctl print <target>` for detailed launchd state.","Verify the plist's Label matches the kickstart target and the Program/ProgramArguments path exists and is executable.","Run the supervisor binary directly to surface any startup crash, fix it, then kickstart again.","Re-bootstrap the plist after fixing it (bootout then bootstrap) before kicking start."],"exampleFix":"// before\n<key>ProgramArguments</key><array><string>/usr/local/bin/myapp-supervisor</string></array>  // binary missing\n// after\n<key>ProgramArguments</key><array><string>~/.local/bin/myapp</string><string>supervisor</string><string>serve</string></array>  // correct, executable path","handlingStrategy":"try-catch","validationCode":"import { execSync, existsSync } from 'node:child_process';\nimport { statSync } from 'node:fs';\nif (process.platform === 'darwin') {\n  const bin = '/path/to/myapp'; // ProgramArguments[0] from plist\n  if (!existsSync(bin) || !(statSync(bin).mode & 0o111)) {\n    throw new Error(`launchd program ${bin} missing or not executable`);\n  }\n  execSync(`launchctl print gui/$(id -u)/${label} > /dev/null 2>&1`); // must be loaded\n}","typeGuard":null,"tryCatchPattern":"try {\n  await supervisorInstallLaunchAgent();\n} catch (e) {\n  if (String(e).includes('launchctl kickstart failed')) {\n    console.error('kickstart failed: verify plist Label matches target and the program path exists/executable.');\n    console.error('Debug with: launchctl print <target>');\n    return;\n  }\n  throw e;\n}","preventionTips":["Ensure the Program/ProgramArguments path in the plist exists and is executable.","Keep the kickstart target label identical to the plist Label key.","Test the supervisor binary runs standalone before installing it as a launch agent.","After editing the plist, bootout + bootstrap before kickstart."],"tags":["macos","launchd","launchctl","process","supervisor"],"backgroundTag":"launchctl-kickstart-failed","analyzedSha":"a747e741ae92c09071d0ae946ab48488adcff1ce","analyzedAt":"2026-09-01T22:43:55.719Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}