The Qualys Cloud Agent is a lightweight, centrally managed sensor that provides continuous visibility into the security posture of your IT assets, whether they reside on-premises, in cloud environments, or on mobile endpoints. It plays a crucial role in modern vulnerability management, compliance, and threat detection strategies by offering real-time data collection without the need for traditional network scans. However, like any complex software, Qualys Agents can encounter issues that prevent them from reporting data effectively. This guide provides practical steps and best practices for troubleshooting common Qualys Agent problems.

Understanding the Qualys Agent Architecture

Before diving into troubleshooting, it’s essential to understand the fundamental components and communication flow of a Qualys Agent. The agent is installed on the host and communicates directly with the Qualys Cloud Platform over HTTPS (port 443). It collects various metadata, including asset inventory, vulnerability data, and compliance posture, based on the assigned configuration profile and manifest. The agent also manages its own updates, ensuring it’s running the latest version with the most recent features and bug fixes.

Key aspects include:

• Continuous Monitoring: Agents constantly assess the host for changes.
• Configuration Profiles: These dictate what data the agent collects and how it behaves.
• Manifests: Instructions downloaded from the cloud platform that specify the metadata to collect.
• Log Files: Critical for diagnosing issues, these files record agent activities and errors.

Common Installation and Registration Issues

A common starting point for agent problems is during the initial installation or registration. If an agent isn’t showing up in the Qualys Cloud Platform, or its status remains “Not Installed,” these are the first areas to investigate.

Prerequisites Not Met

Ensure the host meets the basic requirements for agent installation:

• Operating System Compatibility: Verify the OS version is supported by the Qualys Agent.
• Administrator/Root Privileges: Installation requires local administrator privileges on Windows or root/sudo privileges on Linux/Unix/macOS.
• Network Connectivity: The host must be able to reach the Qualys Cloud Platform over HTTPS port 443.

Incorrect Activation Key or Proxy Settings

During installation, the agent needs an activation key to register with your Qualys subscription.

• Activation Key Validation: Double-check that the activation key used is correct and active.
• Proxy Configuration: If your network requires a proxy for outbound internet access, the agent must be configured to use it.
  • Windows: Proxy settings can be configured using the QualysProxy.exe utility, which stores information in the Qualys registry hive. This tool replaces older methods like netsh winhttp.
  • Linux/Unix/macOS: Proxy settings are typically configured via environment variables (e.g., https_proxy or qualys_https_proxy) in files like /etc/sysconfig/qualys-cloud-agent or /etc/environment.

Troubleshooting Steps:

1. Check Network Connectivity: From the agent host, attempt to reach the Qualys Cloud Platform URL (found in your Qualys account under Help > About) via curl or a web browser to confirm port 443 access.

2. Check Network Connectivity: From the agent host, attempt to reach the Qualys Cloud Platform URL (found in your Qualys account under Help > About) via curl or a web browser to confirm port 443 access. The specific URL will depend on your Qualys platform (e.g., qualysapi.qualys.com for US1). A successful connection attempt with curl might show an HTTP 404 response, which is expected as you’re not making an authenticated API call, but it confirms network reachability.

3. Verify Proxy Configuration:

   • Windows: Ensure the QualysProxy.exe utility located in C:\Program Files\Qualys\QualysAgent\ was run with the correct proxy settings and credentials. This utility encrypts credentials and stores settings in the Qualys registry hive. You can check the agent’s log file (typically C:\ProgramData\Qualys\QualysAgent\Log.txt) for entries indicating whether a proxy was detected or if there were “No WinHTTP proxies defined” messages, which suggest the agent proxy settings are not configured.
   • Linux/Unix/macOS: Confirm that the environment variables (e.g., https_proxy or qualys_https_proxy) are correctly set in files like /etc/sysconfig/qualys-cloud-agent or /etc/default/qualys-cloud-agent. Remember to restart the Qualys Cloud Agent service after modifying these files. Check log files (e.g., /var/log/qualys/qualys-cloud-agent.log) for proxy-related errors or successful proxy connections.

4. Review Agent Log Files for Errors: The log files are invaluable for diagnosing why an agent isn’t installing or registering.

   • Windows: Log files (Log.txt, Archive.txt) are primarily found in C:\ProgramData\Qualys\QualysAgent\. Installer-specific logs like CloudAgentInstaller.log and MsiLog_TimeStamp.log can also be found here for installation issues.
   • Linux/Unix/macOS: Log files are typically located in /var/log/qualys/qualys-cloud-agent.log or /var/opt/qualys/qualys-cloud-agent.log for Unix. Errors related to activation keys (e.g., HTTP 404 if the key is disabled) or communication issues will be logged here. Increasing the LogLevel (to 4 for debug or 5 for trace) can provide more verbose information, but be aware that this might expose sensitive data in clear text.

5. Utilize the Qualys Cloud Agent Health Check Tool: For agents that have installed but aren’t reporting, Qualys provides a local Health Check Tool bundled with the agent for Windows (version 5.5 and later) and Linux (version 6.3 and later). This tool provides a quick assessment of the agent’s overall health, including installation status, communication health, and application functionality, with clear status indicators (good, bad, poor, not installed, not provisioned, or error) and actionable remediation steps.

   • Windows: Run "%programfiles%\qualys\qualysagent\QualysAgentHealthCheck.exe" from an elevated command prompt.
   • Linux: Run /usr/local/qualys/cloud-agent/bin/qualys-healthcheck-tool.

Agent Not Reporting Data Effectively

Even after successful installation and registration, agents may stop reporting data to the Qualys Cloud Platform. This can manifest as outdated “Last Check-in” times or missing vulnerability/compliance data.

1. Verify Qualys Agent Service Status: The agent relies on a running service or daemon to collect and transmit data.

   • Windows: Check the “Services” console (services.msc) to ensure the “Qualys Cloud Agent” service is running. If not, attempt to start it.
   • Linux/Unix/macOS: Use commands like sudo systemctl status qualys-cloud-agent or sudo service qualys-cloud-agent status to verify the daemon’s status. Restart if necessary.

2. Ongoing Network Connectivity Issues: Intermittent network problems, changes in firewall rules, or proxy server issues can prevent an already registered agent from uploading data.

   • Re-run the network connectivity tests mentioned earlier.
   • Check for WinHTTP errors in Windows agent logs (e.g., 12002 for timeout, 12029 for cannot connect, 12175 for SSL certificate issues) which indicate communication failures.
   • If using a proxy, verify its availability and ensure no changes have been made that would impact the agent’s ability to communicate through it.

3. Configuration Profile Problems: The configuration profile dictates what data the agent collects and its behavior. An incorrect or corrupted profile can lead to data collection failures.

   • In the Qualys Cloud Platform, navigate to the Cloud Agent module, then Configuration Profiles. Verify that the assigned profile is active and configured as expected for the target assets.
   • Ensure that data collection for specific modules (VM, PC, SCA, Inventory) has not been inadvertently suspended in the profile settings.
   • Changes to configuration profiles are downloaded by the agent and logged. Check the agent logs for messages indicating successful (or failed) configuration downloads.

4. Manifest Download Failures: The manifest contains instructions for what metadata the agent should collect. If an agent cannot download its manifest, it won’t know what to scan for.

   • Look for “Manifest Downloaded” status in the Qualys UI for the agent.
   • Agent logs will show attempts to download the manifest and any errors encountered during this process.

5. Disk Space or Resource Exhaustion: While Qualys agents are lightweight, continuous operation and data collection require some system resources.

   • Ensure the host has sufficient free disk space for the agent’s database and log files.
   • Monitor CPU and memory usage of the Qualys agent process (e.g., QualysCloudAgent.exe on Windows). While typically low, sustained high usage could indicate an issue. Configuration profiles can be tuned to optimize performance parameters.

6. Corrupted Agent Installation: In rare cases, the agent’s installation might become corrupted, leading to persistent issues. If all other troubleshooting steps fail, a clean reinstallation might be necessary. This involves uninstalling the agent (and purging its record from the Qualys platform if it’s not going to be immediately re-registered) and then reinstalling it with a valid activation key.

Agent Update and Version Control Problems

Qualys Cloud Agents are designed to auto-update, ensuring they run the latest version with security enhancements and bug fixes. However, this process can sometimes encounter issues.

1. Auto-Update Failures:

   • Connectivity: Agents require continuous connectivity to the Qualys Cloud Platform to download updates. Network or proxy issues can prevent updates.
   • Configuration Profile Settings: A common reason for update failures is if the “Prevent auto updating of the agent binaries” setting is enabled in the agent’s configuration profile. This setting should generally be unchecked to allow automatic upgrades.
   • Known Issues: Occasionally, specific agent versions might have known issues that affect self-patching. Refer to Qualys documentation for known issues.
   • Manual Upgrade: If auto-update fails, a manual upgrade can be performed by downloading the latest installer and running it on the host.

2. Version Control Profile Conflicts: Organizations sometimes use Agent Version Control (AVC) profiles to lock agents to specific versions for consistency or testing.

   • Ensure the AVC profile is correctly assigned and prioritized.
   • If an agent is not updating as expected, verify it’s not inadvertently locked to an older version by an AVC profile.
   • Check agent logs for messages related to version control or update attempts.

Advanced Troubleshooting and Best Practices

1. Utilizing Agent Log Files for Deeper Analysis: Beyond basic error checking, the log files offer granular details about agent activities, communication attempts, and data processing.

   • Log Level: For in-depth diagnostics, temporarily increase the log level to “debug” or “trace” in the agent’s configuration (e.g., via registry on Windows or configuration files on Linux). Remember to revert this setting after troubleshooting to avoid excessive log generation.
   • Log Analyzer Tool: Qualys may provide an Agent Log Analyzer Tool to help parse and interpret the extensive log data.
   • Common Errors: Familiarize yourself with common error codes (especially WinHTTP errors for Windows agents) and their meanings to quickly identify the root cause of communication problems.

2. Proactive Monitoring and Agent Health:

   • Regularly monitor the “Cloud Agent” module in your Qualys platform for agent status, last check-in times, and any reported errors.
   • Leverage the Qualys Cloud Agent Health Check Tool not just for reactive troubleshooting but also for proactive health checks, especially after system changes or network modifications.
   • Implement dynamic tagging and dashboards to track agent health at scale and identify trends.

3. Contacting Qualys Support: If you’ve exhausted all troubleshooting steps and the issue persists, contact Qualys Support. Be prepared to provide:

   • The Qualys Cloud Agent log files (collected from the affected host).
   • Details of the host (OS, network configuration, proxy settings).
   • The specific activation key and configuration profile used.
   • Any error messages or status indications observed in the Qualys UI or agent logs.

Related Articles

• BIMI + VMC + CMC: Boost Email Trust & Branding
• Checksums Explained: Data Integrity Fundamentals
• Scaling osquery Deployments
• Quick Guide to Linux Process Management and Job Control

Conclusion

The Qualys Cloud Agent is a vital component for maintaining continuous visibility into your IT asset’s security posture. While robust, understanding its architecture and common failure points is key to effective troubleshooting. By systematically checking prerequisites, network connectivity, agent configurations, and diligently reviewing log files, most common issues can be quickly resolved. Leveraging tools like the Qualys Cloud Agent Health Check Tool and adhering to best practices for configuration and monitoring will ensure your agents remain healthy and continue to provide critical security intelligence to the Qualys Cloud Platform.

References

1. Qualys, Inc. (2025). Cloud Agent Getting Started Guide. Available at: https://www.qualys.com/docs/qualys-cloud-agent-getting-started-guide.pdf [Accessed 15 November 2025].
2. Qualys, Inc. (2025). Troubleshooting Cloud Agent. Available at: https://www.qualys.com/docs/qualys-cloud-agent-troubleshooting.pdf [Accessed 15 November 2025].
3. Qualys, Inc. (2025). Qualys Cloud Agent Health Check Tool. Available at: https://www.qualys.com/docs/qualys-cloud-agent-health-check-tool.pdf [Accessed 15 November 2025].
4. Qualys, Inc. (2025). Qualys Performance Tuning Series: Qualys Cloud Agent Configuration Best Practice. Available at: https://community.qualys.com/s/article/Qualys-Performance-Tuning-Series-Qualys-Cloud-Agent-Configuration-Best-Practice [Accessed 15 November 2025].
5. Qualys, Inc. (2025). Upgrading Qualys Cloud Agents. Available at: https://community.qualys.com/s/article/Upgrading-Qualys-Cloud-Agents [Accessed 15 November 2025].