Diagnosing agent deployment failures

This article helps you diagnose EDR agent deployment failures, including agents that fail to install, do not start after installation, or install successfully but do not appear in the console or check in. It covers common deployment methods, such as GPO, RMM, manual installation, and PowerShell scripts, and walks through identifying the failure type, determining scope, and collecting the details needed to resolve or escalate the issue.

Symptoms

  • The agent installer does not start on one or more endpoints.
  • Installation completes, but the agent service does not start or is not running.
  • The agent installs and runs locally, but does not appear in the console or check in.

Causes

Failures can occur at any stage of the deployment process. The installer might not start, might stop partway through, or might finish without the agent running or checking in. Root causes vary by deployment method and environment, and can include:

  • Permission issues on the endpoint.
  • Policy restrictions, such as Group Policy or endpoint security software.
  • Network connectivity problems that prevent the agent from reaching the Kaseya server.
  • Software conflicts on the endpoint.
  • Misconfigured deployment scripts.

Resolution steps

To resolve this issue, complete the following steps in order, gathering information at each step before proceeding to the next:

  1. Identify the deployment method used for the failing endpoints. The deployment method determines which logs to review and which remediation steps apply.

    • GPO (Group Policy): Agent deployed using an Active Directory Group Policy Object.
    • DRMM / RMM: Deployed through a remote monitoring and management tool, such as Datto or ConnectWise.
    • Manual: Installer downloaded and run directly on the endpoint.
    • PowerShell script: Automated deployment using a PowerShell script.

  2. Classify the failure type. Identify the specific failure behavior reported or observed. This determines which logs and checks are relevant in later steps.

    • Installation won't start: The installer does not launch; no process is created on the endpoint.
    • Installation fails partway through: The installer starts but stops before completing, often with an error code.
    • Installation completes but agent is not running: The installer reports success, but the agent service is absent or stopped.
    • Agent installed but not checking in: The agent service is running, but no heartbeat appears in the console.
    • Agent installed but not visible in console: The agent appears to be running locally, but is not registered in the management console.

  3. Determine the scope of impact. Establish how many endpoints are affected. A wider scope indicates a systemic issue, such as a policy change or network block, rather than an endpoint-specific problem.

    • 0–10 machines: Likely endpoint-specific. Proceed with per-device troubleshooting.
    • 11–50 machines: Possible shared environment factor. Check for common OS versions, OU membership, or network segment.
    • 50+ machines: Systemic issue.

  4. Attempt initial remediation based on what has already been tried:

    • No prior attempt: Retry the deployment using the same method. Note any error codes or messages that appear during the retry.
    • Retried with the same method: Switch to a different deployment method (for example, switch from GPO to manual installation on one endpoint) to determine whether the issue is method-specific.
    • Multiple attempts with different methods: Do not retry further. Continue to step 5 to collect logs and error details for review.

    If the deployment method is GPO, verify that the GPO is linked to the correct OU and that the target machines have received the updated policy (gpupdate /force).

  5. Collect error details. If error messages or exit codes are present, record them exactly as they appear:

    • Copy the full text of any error message displayed during installation.
    • Note the exact exit code or error code returned by the installer or deployment tool.

    If no error message is displayed, note this explicitly and continue to step 6.

  6. Collect endpoint details. For all affected endpoints, gather the following information before closing the triage or submitting a support ticket:

    • Host names of the machines where installation failed
    • Operating system version and build number (for example, Windows 10 22H2, Windows Server 2019)
    • Deployment method used
    • Chronological summary of all remediation attempts
    • Full error messages and exit codes
    • Scope of impact (number of affected machines)
    • Logs, if present:
      • Windows: %ProgramFiles%\infocyte\agent\logs\agent-YYYY-MM-dd.log
      • macOS: /usr/local/infocyte/agent/logs/agent-YYYY-MM-dd.log
      • Linux: /opt/infocyte/agent/logs/agent-YYYY-MM-dd.log

NOTE  For agents that install successfully but do not check in, verify that the endpoint can reach the Kaseya server on the required ports. Firewall rules and proxy settings are common causes of check-in failures that do not produce installer errors. See Endpoint firewall and networking requirements for the Endpoint Security agent.

Tips and tricks

  • Test on a single endpoint first. Before redeploying to all affected machines, test the corrected deployment on one endpoint to confirm the fix works before a broader rollout.
  • Use manual installation to isolate method-specific issues. If an automated deployment method (GPO, RMM, or script) is failing, a manual installation on the same endpoint can quickly confirm whether the issue is with the method or the endpoint itself.

Related articles

 

Revision Date
Initial release. 7/6/26