Overview 💥
Installing the Liongard Windows Agent is typically straightforward; however, installation failures can occur due to environmental constraints, security controls, legacy remnants, or endpoint configuration conflicts.
This article provides a progressive, escalation-based troubleshooting framework to diagnose and resolve Windows Agent installation failures, from basic validation through advanced remediation using the Liongard Agent Install Script.
‼️Note : This guide assumes the reader has administrative access to the endpoint and working knowledge of Windows services, event logs, and endpoint security tooling.
What This Article Covers 📔
Pre-installation validation requirements
Known causes of MSI installation failure
Service startup and permission failures
Logging and diagnostic techniques
Advanced remediation using the official install script
Evidence collection standards for Support escalation
Pre-Installation Requirements 🗒️
Before troubleshooting, confirm these baseline conditions:
Requirement | Details |
OS Support | Windows Server 2016+ (2012 only supported with agent 4.2.3) |
Privileges | Installer must be executed as Local Administrator |
Service Account | Agent must run as SYSTEM (custom service accounts are unsupported) |
Network | Outbound HTTPS (TCP 443) allowed |
Memory | 1 GB of usable RAM |
Disk Space | 1 GB of free disk space |
CPU Architecture | x64 |
Virtual Machines | We recommend a minimum of 2 processors |
⚠️ Installing the agent under a domain or user account is unsupported and frequently causes update and service failures.
Common Root Causes of Installation Failure 🤒
Installation issues typically fall into one or more of the following categories:
🔐 Permission & Identity Issues
MSI not executed with elevated privileges
Agent installed under a non-SYSTEM account
Locked or conflicting Windows services
🧩 Legacy Agent Remnants
Older Liongard agent versions blocking upgrade
Incomplete uninstall leaving services or registry entries
GUID collisions with existing agent records
🛡️ Security Interference
Antivirus / EDR blocking MSI execution
Endpoint firewall preventing outbound communication
Scheduled task removal by security software
🌐 Configuration Errors
Incorrect Environment URL
Invalid Access Key or Key Secret
Environment name mismatch
Steps to Resolve 🧑🏫
Step 1: Validate Configuration Inputs
Before attempting installation, verify all configuration parameters:
Environment URL (no trailing slashes or whitespace)
Agent Install Access Key & Key Secret
❌ Placeholder or malformed values will cause silent MSI failure.
Step 2: Remove Legacy or Broken Agent Installations
Older or corrupted agents can block upgrades or reinstallation.
Standard Removal
Open Control Panel → Programs & Features
Uninstall Liongard Agent
Confirm removal of:
C:\Program Files (x86)\LiongardInc\LiongardAgent
Registry Cleanup (If Installation Continues to Fail)
Open Registry Editor
Navigate to:
HKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application
Locate and delete:
LiongardAgentSVC
⚠️ Export registry keys before deletion as a precaution.
Step 3: Perform MSI Installation with Full Logging
If GUI installation fails or provides no useful feedback, logging is mandatory.
Run the MSI from an elevated command prompt:
msiexec.exe /i "C:\Liongard\LiongardAgent-lts.msi" /L*V "C:\Liongard\AgentInstall.log"
What to Look for in Logs
Return value 3Error
1603System.Net.WebExceptionPermission or service startup failures
🧠 MSI logs are the primary diagnostic artifact for Support.
Step 4: Validate Firewall, Antivirus, and EDR Behavior
Security tooling is a very common silent blocker.
Check for:
MSI execution blocking
Service creation denial
Scheduled task deletion
Network traffic inspection blocking HTTPS
Recommended test:
Temporarily disable endpoint security
Retry installation
Re-enable security post-install
🔐 Ensure Liongard directories and executables are allowlisted after installation.
Step 5: Advanced Remediation — Use the Liongard Agent Install Script
If MSI installation fails repeatedly, do not continue manual retries.
Why This Script Is the Preferred Fallback 🧐
The script performs logic the MSI cannot:
Capability | Purpose |
Silent MSI install | Eliminates user prompts |
Input validation | Prevents empty or invalid config |
Environment matching | Confirms environment exists |
GUID collision detection | Prevents agent overwrite |
Controlled uninstall | Removes services, folders, registry |
Backend cleanup (conditional) | Prevents orphaned agents |
Full transcript logging | Captures every decision made |
Logs Generated by the Script 📔
Log Type8 | Path |
Script Transcript |
|
MSI Install Log |
|
✅ These logs are essential for support escalation, as they contain important information that can help diagnose installation issues.
Step 6: Post-Installation Validation
After installation completes:
Open Services
Confirm LiongardAgentSVC is running
Navigate to Admin > Agents in Liongard
Confirm:
Agent is Active
Correct Environment assignment
Trigger an inspection to confirm runtime health
Other Log Collection Locations 💻
Main logs:
C:\Program Files (x86)\LiongardInc\LiongardAgent\logs
Service log:
C:\Program Files (x86)\LiongardInc\LiongardAgent\AgentSVCLog.txt
Event Viewer:
Application and Service Logs → LiongardAgentLogs
Frequently Asked Questions 🙋♂️
Why must the agent run as SYSTEM?
SYSTEM is always present
No password rotation
Least-privilege enforcement
Required for auto-update scheduler
Why does auto-update stop working?
Scheduled task removed by EDR
Agent not running as SYSTEM
Endpoint offline at scheduled update time
Why does the agent appear but show “Agent Issues”?
Agent service offline
Network connectivity blocked
Can I retry MSI repeatedly?
❌ No. Repeated failures indicate environmental issues. Use the script.
When to Contact Support 🦁
If all steps above fail, Use Support Chat within the Liongard platform
Provide ALL of the following:
Windows OS version
Agent version attempted
Installation method (MSI or Script)
Auto-update enabled/disabled
Exact error messages
Screenshots of failures
MSI install log
Script transcript log
Relevant Event Viewer entries
🚨 Tickets without logs will be delayed.
Summary 🤩
Most installation failures are environmental, not agent defects
MSI logging is non-optional for troubleshooting
The install script is the authoritative fallback
SYSTEM context is mandatory
Logs are required for Support escalation