Overview 💥
During installation of the Liongard Windows Agent, you may encounter Error 500 (Internal Server Error). This error typically occurs during the agent registration phase, when the installer attempts to communicate with Liongard’s API.
While the error message references a server-side failure, this issue is most commonly caused by local endpoint conditions that prevent successful registration or secure communication.
What Does Error 500 Mean in This Context? 🤔
An example error message may look like:
System.Net.WebException: The remote server returned an error: (500) Internal Server Error.
at System.Net.HttpWebRequest.GetResponse()
at LiongardAgentShared.Services.API.ApiClient.GetResponse(HttpWebRequest request)
at LiongardAgentShared.Services.API.ApiClient.RegisterNewAgent(AgentRegistrationRequest agentRegistrationRequest)
CustomAction RegisterAgent returned actual error code 1603 (note this may not be 100% accurate if translation happened inside sandbox)
Key takeaway:
This does NOT usually indicate an outage or failure on Liongard’s servers.
It typically indicates that the agent could not successfully register due to local system, configuration, or security controls.
Common Causes 🤒
Error 500 during agent installation is often associated with one or more of the following:
Firewall, proxy, or SSL inspection blocking outbound HTTPS traffic
Antivirus or EDR interfering with MSI custom actions
TLS or certificate validation issues on the endpoint
Duplicate or conflicting MachineGuid / Device GUID
Previously failed or partial agent installations
Environment name mismatch during registration
Endpoint unable to reach Liongard API endpoints during install
Recommended Troubleshooting Steps (In Order) 🧑🏫
1️⃣ Connect to the Host Device
Ensure you are logged into the exact Windows device where the Liongard Agent needs to be installed.
2️⃣ Download a Known Working Agent Version
Download Agent version 4.2.4 using the provided link:
‼️ This version is known to install successfully in scenarios where newer installers initially fail to register.
3️⃣ Install the Agent
Run the installer and proceed through the standard installation process.
Do not specify a custom service account
Allow the agent to install using the default SYSTEM context
4️⃣ Verify Installation
After installation completes:
Open Control Panel → Programs & Features
Confirm Liongard Agent appears in the installed applications list
5️⃣ Manually Trigger the Agent Update
Open Task Scheduler
Navigate to the Liongard folder
Locate the Liongard Agent Updater task
Click and select Run
6️⃣ Confirm the Agent Version
Once the update task completes:
Recheck Programs & Features
Confirm the agent has updated to the latest available version
✅ If the agent updates successfully, no further action is required.
If the above Steps Do NOT Resolve the Issue 🧐
If Error 500 persists or the agent fails to register or update after completing the steps above, proceed with the advanced troubleshooting steps below.
Use the Liongard Agent Install Script
If the MSI installation or manual update fails, Liongard strongly recommends using the Agent Install Script, which handles edge cases the MSI alone cannot.
Why This Script Works Better
The script adds safeguards and diagnostics, including:
Capability | What It Solves |
Silent MSI execution | Avoids UI-based MSI failures |
Configuration validation | Prevents invalid URL, key, or environment values |
Environment name matching | Ensures correct environment assignment |
MachineGuid collision detection | Prevents duplicate or overwritten agents |
Optional uninstall before install | Cleans up failed or partial installs |
Backend record cleanup (scored) | Removes orphaned agents only when safe |
Full transcript logging | Captures decision logic and failures |
MSI installer logging | Provides clear install exit codes |
Logs to Collect After Running the Script 👨💻
After running the script, if failure persist collect both logs:
Script Transcript & Diagnostics
C:\Liongard\LGAgentScript_<timestamp>.log
MSI Installer Log
C:\Liongard\AgentInstall.log
📌 These logs are critical for identifying registration, network, or identity-related failures.
After Installation: Validation Checklist 🗒️
Once installation completes:
Confirm LiongardAgentSVC is running
Verify the agent appears in Admin → Agents
Confirm heartbeat status is Online
Ensure the agent is assigned to the correct Environment
Allow at least one inspection cycle to complete
FAQ's 🙋♂️
Q: Does Error 500 mean Liongard is down?
No. In nearly all cases, Error 500 during installation is caused by endpoint-side restrictions or configuration issues.
Q: Can antivirus or EDR cause this error?
Yes. MSI custom actions, outbound HTTPS calls, or service creation can be blocked, resulting in registration failure.
Q: Should I keep retrying the MSI?
No. If the MSI fails once with Error 500, move directly to the Agent Install Script to avoid partial installs.
Q: Will reinstalling overwrite an existing agent?
The script explicitly checks for MachineGuid collisions and only overrides when necessary, preventing unintended overwrites.
When to Contact Support 🦁
If the issue persists after using the Agent Install Script, contact Liongard Support.
Please include the following with your ticket:
Screenshot or exact text of the Error 500 message
Troubleshooting steps attempted
Windows OS version
Confirmation of firewall / proxy testing
AgentInstall.log
LGAgentScript_<timestamp>.log
Relevant Windows Event Viewer errors
Any EDR / AV exclusions applied
📌 Providing logs upfront significantly reduces resolution time.
Summary 🤩
Error 500 during Windows Agent installation is typically endpoint-related, not server-side
Network security, TLS, EDR, or registration conflicts are common causes
The Liongard Agent Install Script is the recommended remediation
Logs generated by the script are essential for deeper troubleshooting