Overview 💥
A common cause is the use of the @ character within the proxy authentication password. Because the Liongard Agent proxy configuration expects the proxy URL to follow a standard URL format, the @ character is interpreted as a delimiter between credentials and the proxy server address, resulting in an invalid proxy URL.
Symptoms 🤒
You may observe one or more of the following:
Windows Agent installation completes, but the Agent fails to communicate with Liongard.
Linux Agent installation fails to establish connectivity after installation.
Agent remains Offline or displays No Heartbeat status.
Agent logs indicate proxy configuration or connectivity errors.
Proxy-authenticated environments fail while the same installation succeeds when proxy settings are removed.
Why Does This Happen? 🤔
Liongard's proxy configuration requires the proxy URL to be supplied in the following format:
proxytype://username:password@server:port
For example:
http://lion:password@proxy.company.com:8888
In this format, the @ symbol separates the authentication credentials from the proxy server address. If the password itself contains an additional @ character, the URL becomes ambiguous and is parsed incorrectly by the installer or agent service.
Example
❌ Invalid
http://proxyuser:P@ssword123@proxy.company.com:8080
The agent interprets the first @ as the end of the password, causing the remaining value to be processed incorrectly.
✅ Valid
Use a password that does not contain reserved URL characters such as @, or update the proxy credentials accordingly before installation.
http://proxyuser:Passw0rd123@proxy.company.com:8080
Steps to Resolve 🧑🏫
Step 1: Review Proxy Authentication Credentials
Verify whether the proxy authentication password contains an @ character.
Step 2: Update Proxy Credentials
If possible, modify the proxy account password to remove the @ character.
Step 3: Reinstall or Reconfigure the Agent
For Windows:
PROXYURL="http://username:password@server:port"
For Linux:
sudo ./LiongardAgent-lts-x64.xz.run -- -u InstanceURL -k AccessKey -s AccessSecret -p http://username:password@server:port
Use the updated password that does not contain the @ character.
Step 4: Restart and Verify
After updating the proxy configuration:
Restart the Liongard Agent service.
Confirm the Agent checks in successfully.
Verify the Agent status changes to Online in Liongard.
Verification Steps 👨🔧
Windows
Confirm the Agent service is running.
Verify the proxy URL configured in the installation parameters or environment variable.
Check that the Agent successfully appears online in Liongard.
Linux
Verify the service status:
systemctl status liongard-agent
2. Review heartbeat logs:
tail -f /opt/liongard/logs/heartbeat.log
3. Confirm the Agent transitions to an Online state.
Best Practices 🙌
Avoid using reserved URL characters in proxy authentication passwords when configuring Liongard Agents.
Validate proxy URLs before deployment.
Test proxy-authenticated installations on a single endpoint before mass deployment.
For scripted deployments, verify the complete proxy URL format is valid and properly parsed by the operating system and deployment tool.