---
title: Troubleshoot Elastic Defend
description: This topic covers common troubleshooting issues when using Elastic Defend's endpoint management tools. In some cases, an Unhealthy Elastic Agent status...
url: https://www.elastic.co/elastic/docs-builder/docs/3016/troubleshoot/security/elastic-defend
products:
- Elastic Cloud Serverless
- Elastic Security
applies_to:
- Serverless Security projects: Generally available
- Elastic Stack: Generally available
---
# Troubleshoot Elastic Defend
This topic covers common troubleshooting issues when using Elastic Defend's [endpoint management tools](https://www.elastic.co/elastic/docs-builder/docs/3016/solutions/security/manage-elastic-defend).
## Unhealthy Elastic Agent status
In some cases, an `Unhealthy` Elastic Agent status may be caused by a failure in the Elastic Defend integration policy. In this situation, the integration and any failing features are flagged on the agent details page in Fleet. Expand each section and subsection to display individual responses from the agent.
Integration policy response information is also available from the **Endpoints** page in the Elastic Security app (**Manage** → **Endpoints**, then click the link in the **Policy status** column).
Common causes of failure in the Elastic Defend integration policy include missing prerequisites or unexpected system configuration. Consult the following topics to resolve a specific error:
- [Approve the system extension for Elastic Endpoint](/elastic/docs-builder/docs/3016/solutions/security/configure-elastic-defend/enable-access-for-macos#system-extension-endpoint) (macOS)
- [Enable Full Disk Access for Elastic Endpoint](/elastic/docs-builder/docs/3016/solutions/security/configure-elastic-defend/enable-access-for-macos#enable-fda-endpoint) (macOS)
- [Resolve a potential system deadlock](#linux-deadlock) (Linux)
If the Elastic Defend integration policy is not the cause of the `Unhealthy` agent status, refer to [Common problems with Fleet and Elastic Agent](https://www.elastic.co/elastic/docs-builder/docs/3016/troubleshoot/ingest/fleet/common-problems) for help with the Elastic Agent.
## Disabled to avoid potential system deadlock (Linux)
If you have an `Unhealthy` Elastic Agent status with the message `Disabled due to potential system deadlock`, that means malware protection was disabled on the Elastic Defend integration policy due to errors while monitoring a Linux host.
You can resolve the issue by configuring the policy’s [advanced settings](https://www.elastic.co/elastic/docs-builder/docs/3016/solutions/security/configure-elastic-defend/configure-linux-file-system-monitoring) related to **fanotify**, a Linux feature that monitors file system events. By default, Elastic Defend works with fanotify to monitor specific file system types that Elastic has tested for compatibility, and ignores other unknown file system types.
If your network includes nonstandard, proprietary, or otherwise unrecognized Linux file systems that cause errors while being monitored, you can configure Elastic Defend to ignore those file systems. This allows Elastic Defend to resume monitoring and protecting the hosts on the integration policy.
Ignoring file systems can create gaps in your security coverage. Use additional security layers for any file systems ignored by Elastic Defend.
To resolve the potential system deadlock error:
1. Go to **Manage** → **Policies**, then click a policy’s name.
2. Scroll to the bottom of the policy and click **Show advanced settings**.
3. In the setting `linux.advanced.fanotify.ignored_filesystems`, enter a comma-separated list of file system names to ignore, as they appear in `/proc/filesystems` (for example: `ext4,tmpfs`). Refer to [Find file system names](/elastic/docs-builder/docs/3016/solutions/security/configure-elastic-defend/configure-linux-file-system-monitoring#find-file-system-names) for more on determining the file system names.
4. Click **Save**.
Once you save the policy, malware protection is re-enabled.
## Required transform failed
If you encounter a `“Required transform failed”` notice on the Endpoints page, you can usually resolve the issue by restarting the transform. Refer to [Transforming data](https://www.elastic.co/elastic/docs-builder/docs/3016/explore-analyze/transforms) for more information about transforms.
To restart a transform that’s not running:
1. Go to Kibana's **Transforms** management page using the navigation menu or the [global search field](https://www.elastic.co/elastic/docs-builder/docs/3016/explore-analyze/find-and-organize/find-apps-and-objects).
2. Enter `endpoint.metadata` in the search box to find the transforms for Elastic Defend.
3. Click the **Actions** menu (**…**) and do one of the following for each transform, depending on the value in the **Status** column:
- `stopped`: Select **Start** to restart the transform.
- `failed`: Select **Stop** to first stop the transform, and then select **Start** to restart it.
4. On the confirmation message that displays, click **Start** to restart the transform.
5. The transform’s status changes to `started`. If it doesn’t change, refresh the page.
## Elastic Agent and Elastic Endpoint connection issues
After Elastic Agent installs Elastic Endpoint, Elastic Endpoint connects to Elastic Agent to report its health status and receive policy updates and response action requests. If that connection cannot be established, the Elastic Defend integration will cause Elastic Agent to be in an `Unhealthy` status, and Elastic Endpoint won’t operate properly.
### Identify if the issue is happening
You can identify if this issue is happening in the following ways:
- Run Elastic Agent's status command:
- `sudo /opt/Elastic/Agent/elastic-agent status` (Linux)
- `sudo /Library/Elastic/Agent/elastic-agent status` (macOS)
- `c:\Program Files\Elastic\Agent\elastic-agent.exe status` (Windows)
If the status result for `endpoint-security` says that Elastic Endpoint has missed check-ins, it might indicate this problem is occurring.
- Run Elastic Endpoint's status command:
- `sudo /opt/Elastic/Endpoint/elastic-endpoint status` (Linux)
- `sudo /Library/Elastic/Endpoint/elastic-endpoint status` (macOS)
- `c:\Program Files\Elastic\Endpoint\elastic-endpoint.exe status` (Windows)
If the problem starts happening right after installing Elastic Endpoint, the output is:
```shell
- elastic-agent
- status: (FAILED) Not connected
- elastic-endpoint
- status: (HEALTHY) Running (no policy)
```
Otherwise, if Elastic Endpoint has been running correctly for a while, the output is:
```shell
- elastic-agent
- status: (FAILED) Not connected
- elastic-endpoint
- status: (HEALTHY) Running
```
In this case, the Elastic Endpoint service is orphaned — policy changes and response action requests cannot reach it. After a few minutes in this state, Elastic Endpoint notifies the Elastic Stack, which changes the Elastic Agent status to `Orphaned`.
Appending `--output full` to the `status` command shows the details of the last policy that Elastic Endpoint was configured with before it lost connection with Elastic Agent.
- You can also examine the full policy details by running:
- `sudo /opt/Elastic/Agent/elastic-agent inspect` (Linux)
- `sudo /Library/Elastic/Agent/elastic-agent inspect` (macOS)
- `c:\Program Files\Elastic\Agent\elastic-agent.exe inspect` (Windows)
If the output shows a policy with name `initial`, revision `0`, and IDs `00000000-0000-0000-0000-000000000000`, Elastic Endpoint was not configured since installation. This corresponds to the status `(HEALTHY) Running (no policy)`.
### Examine Elastic Endpoint logs
If you’ve confirmed that the issue is happening, you can look at Elastic Endpoint log messages to identify the cause:
- `Unable to retrieve connection info from Agent` means that Elastic Endpoint was not able to connect to Elastic Agent.
- `Failed to create bootstrap` indicates you should check if Elastic Agent service is running.
- `Agent process is not root/admin or validation failed, disconnecting` means that Elastic Endpoint is not able to create an initial connection to Elastic Agent as the process is not trusted.
- `Agent GRPC connection failed to establish within deadline` means that Elastic Endpoint's original connection to Elastic Agent worked, but the connection over port `6789` is failing.
### Resolve the issue
To debug and resolve the issue, follow these steps:
1. Make sure nothing else on your device is listening on port `6789` by running:
- `sudo netstat -anp --tcp` (Linux)
- `sudo netstat -an -f inet` (macOS)
- `netstat -an` (Windows)
2. Make sure `localhost` can be resolved to `127.0.0.1` by running:
- `ping -4 -c 1 localhost` (Linux)
- `ping -c 1 localhost` (macOS)
- `ping -4 localhost` (Windows)
## Elastic Defend deployment issues
After deploying Elastic Defend, you might encounter warnings or errors in the endpoint’s **Policy status** in Fleet if your mobile device management (MDM) is misconfigured or certain permissions for Elastic Endpoint aren’t granted. The following sections explain issues that can cause warnings or failures in the endpoint’s policy status.
### Connect Kernel has failed
This means that the system extension or kernel extension was not approved. Consult the following topics for approving the system extension with or without MDM:
- [Approve the system extension with MDM](/elastic/docs-builder/docs/3016/solutions/security/configure-elastic-defend/deploy-on-macos-with-mdm#system-extension-jamf)
- [Approve the system extension without MDM](/elastic/docs-builder/docs/3016/solutions/security/configure-elastic-defend/enable-access-for-macos#system-extension-endpoint)
You can validate the system extension is loaded by running:
```shell
sudo systemextensionsctl list | grep co.elastic.systemextension
```
In the command output, the system extension should be marked as "active enabled".
### Connect Kernel has failed and the system extension is loaded
If the system extension is loaded and kernel connection still fails, this means that Full Disk Access was not granted. Elastic Endpoint requires Full Disk Access to subscribe to system events through the Elastic Defend framework, which is one of the primary sources of eventing information used by Elastic Endpoint. Consult the following topics for granting Full Disk Access with or without MDM:
- [Enable Full Disk Access with MDM](/elastic/docs-builder/docs/3016/solutions/security/configure-elastic-defend/deploy-on-macos-with-mdm#fda-jamf)
- [Enable Full Disk Access without MDM](/elastic/docs-builder/docs/3016/solutions/security/configure-elastic-defend/enable-access-for-macos#enable-fda-endpoint)
You can validate that Full Disk Access is approved by running
```shell
sudo /Library/Elastic/Endpoint/elastic-endpoint test install
```
If the command output doesn’t contain a message about enabling Full Disk Access, the approval was successful.
### Detect Network Events has failed
This means that the network extension content filtering was not approved. Consult the following topics for approving network content filtering with or without MDM:
- [Approve network content filtering with MDM](/elastic/docs-builder/docs/3016/solutions/security/configure-elastic-defend/deploy-on-macos-with-mdm#content-filtering-jamf)
- [Approve network content filtering without MDM](/elastic/docs-builder/docs/3016/solutions/security/configure-elastic-defend/enable-access-for-macos#allow-filter-content)
You can validate that network content filtering is approved by running
```shell
sudo /Library/Elastic/Endpoint/elastic-endpoint test install
```
If the command output doesn’t contain a message about approving network content filtering, the approval was successful.
### Full Disk Access has a warning
This means that Full Disk Access was not granted for one or all Elastic Endpoint components. Consult the following topics for granting Full Disk Access with or without MDM:
- [Enable Full Disk Access with MDM](/elastic/docs-builder/docs/3016/solutions/security/configure-elastic-defend/deploy-on-macos-with-mdm#fda-jamf)
- [Enable Full Disk Access without MDM](/elastic/docs-builder/docs/3016/solutions/security/configure-elastic-defend/enable-access-for-macos#enable-fda-endpoint)
You can validate that Full Disk Access is approved by running
```shell
sudo /Library/Elastic/Endpoint/elastic-endpoint test install
```
If the command output doesn’t contain a message about enabling Full Disk Access, the approval was successful.
## Disable Elastic Defend's self-healing feature on Windows
### Volume Snapshot Service issues
Elastic Defend's self-healing feature rolls back recent filesystem changes when a prevention alert is triggered. This feature uses the Windows Volume Snapshot Service. Although it’s uncommon for this to cause issues, you can turn off this Elastic Defend feature if needed.
If issues occur and the self-healing feature is enabled, you can turn it off by setting `windows.advanced.alerts.rollback.self_healing.enabled` to `false` in the integration policy advanced settings. Refer to [Configure self-healing rollback for Windows endpoints](https://www.elastic.co/elastic/docs-builder/docs/3016/solutions/security/configure-elastic-defend/configure-self-healing-rollback-for-windows-endpoints) for more information.
Elastic Defend may also use the Volume Snapshot Service to ensure the feature works properly even when it’s turned off. To opt out of this, set `windows.advanced.diagnostic.rollback_telemetry_enabled` to `false` in the same settings.
### Known compatibility issues
There are some known compatibility issues between Elastic Defend's self-healing feature and filesystem replication features, including [DFS Replication](https://learn.microsoft.com/en-us/windows-server/storage/dfs-replication/dfsr-overview) and Veeam Replication. This may manifest as `DFSR Event ID 1102`:
`The DFS Replication service has temporarily stopped replication because another application is performing a backup or restore operation. Replication will resume after the backup or restore operation has finished.`
There are no known workarounds for this issue other than to turn off the self-healing feature.
## Failed to download user artifacts
This problem can be identified if `download_user_artifacts` (Download User Artifacts) fails in Elastic Endpoint's policy response.
When Elastic Endpoint is unable to download user artifacts (such as Elastic Endpoint exceptions or trusted applications), it fails to apply the policy because without the right exceptions in place, Elastic Endpoint could have undesired behavior.
Elastic Endpoint caches artifacts locally and keeps trying to download them when necessary, so this problem often resolves itself. If it doesn't, the most common causes are network connection issues or TLS/SSL certificate validation errors. Run the following command for diagnostic information:
- `sudo /opt/Elastic/Endpoint/elastic-endpoint test output` (Linux)
- `sudo /Library/Elastic/Endpoint/elastic-endpoint test output` (macOS)
- `c:\Program Files\Elastic\Endpoint\elastic-endpoint.exe test output` (Windows)
If network connectivity is the problem and the output doesn't clarify the issue, consider using a tool like `curl` for further diagnosis. If incorrect proxy information is displayed, review the proxy configuration, which you can override from the Elastic Defend [advanced settings](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/security/defend-advanced-settings). For certificate issues, check the Fleet Server configuration and consider using one of the `advanced.artifacts.user.*` Elastic Defend advanced settings.
If those steps don't surface the problem, it can occasionally help to make a small edit to the failing artifact(s) — for example, adding an item — to refresh the data that Elastic Agent is trying to download.
## Protection artifacts are out of date
This problem can be identified if `download_global_artifacts` (Download Global Artifacts) fails in Elastic Endpoint's policy response with a message like `Global artifacts snapshot {version} does not match target snapshot: {date}`.
This means artifact snapshots are enabled, but the artifacts currently in use don't yet match the expected snapshot. This is typically due to propagation delays on the Elastic Global Artifacts CDN (or self-hosted mirror). Elastic Endpoint should fetch the requested artifacts once they're available.
For troubleshooting, run:
- `sudo /opt/Elastic/Endpoint/elastic-endpoint test output` (Linux)
- `sudo /Library/Elastic/Endpoint/elastic-endpoint test output` (macOS)
- `c:\Program Files\Elastic\Endpoint\elastic-endpoint.exe test output` (Windows)
The version value `latest` is a special label that means "no snapshot — use the most recent artifacts." This status can appear whenever a new snapshot is set in policy — for example, during a transition from `latest` to `YYYY-MM-DD`, or from one `YYYY-MM-DD` date to another.
## Failed to connect to driver on Windows
This problem can be identified if `connect_kernel` (Connect Kernel) fails on Windows.
This often happens because the Elastic Endpoint service started before the driver. It should auto-resolve in a few seconds.
Rarely, the driver service might be in a delete-pending state due to an installation issue. This can be caused by a local administrator's failed attempt to stop or delete the `ElasticEndpointDriver` service. Rebooting the system resolves the issue.