Manual Chapter : Troubleshoot Health Engine Issues

Updated Date: 10/27/2026

Troubleshoot Health Engine Issues

This guide helps you diagnose and resolve common issues with the F5OS health engine. If you can’t find a solution here, capture a qkview and contact F5 Support.

The health engine run completes, but the run result reports failure.

A run result of failure means that one or more heuristic scripts returned a result with a severity of error, critical, alert, or emergency.

  1. Check the run results file at ${log-dir}/results.json to identify which heuristic scripts reported failures.

  2. Review the individual result file for each failing heuristic at ${log-dir}/<heuristic-id>.<iteration>/result.json.

  3. Follow the recommended actions listed in the result. You can also view recommendations through the confd CLI:

    show system health recommendations nodes node recommendation

  4. After you complete the recommended actions, run the heuristics again to confirm the issue is resolved.

The system health status reports OK, but the system health summary reports Unhealthy for one or more blades.

In F5OS versions prior to v2.0.0, the system health status reflects only the diag-agent component model for the partition. Blade components are not included in the partition’s component model. This means the system health status can show OK even when a blade is unhealthy.

The system health summary checks blades separately and reports accurately.

  • Run the system health summary CLI command to get the complete health picture, including blade status.
  • Review the system health recommendations for any blade-level actions.

You generated a qkview, but it does not contain health engine logs.

The engine writes logs to /var/log/h-engine/. If no heuristics have been run, this directory may be empty or may not exist.

When the engine is run by the diag-agent, results are stored in the agent.db database, whose content is included in qkview automatically.

  1. Confirm that heuristics have been run at least once by checking for log files:

    ls /var/log/h-engine/

  2. If no logs exist, run the health engine manually and then generate a new qkview.

  3. If you ran heuristics through the diag-agent, check that the agent.db content is present in the qkview.

The health engine running inside the platform-monitor container cannot execute commands on the base OS.

The h-engine-tunnel service may not be running, or the security checks may be rejecting the connection. The tunnel validates:

  • Caller identity through SO_PEERCRED (must be h-engine or platform-monitor)

  1. Verify the h-engine-tunnel service is running:

    systemctl status h-engine-tunnel

Note: If the tunnel service is not running, use the systemctl start h-engine-tunnel command to start the tunnel service.

  1. Check that the calling process is h-engine or platform-monitor. Other executables are rejected by the identity verification check.
  2. Review the h-engine-tunnel logs for specific error messages.