# General Oneagent update Issues and troubleshooting

**URL:** <https://community.dynatrace.com/t/general-oneagent-update-issues-and-troubleshooting/48997>\
**Category:** Troubleshooting\
**Tags:** updates, dynatrace-managed, dynatrace-saas, oneagent\
**Created:** [November 21, 2024, 8:11am UTC](https://community.dynatrace.com/t/general-oneagent-update-issues-and-troubleshooting/48997 "2024-11-21T08:11:35Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![noel\_david](https://avatars.discourse-cdn.com/v4/letter/n/3ec8ea/32.png) [@noel\_david](https://community.dynatrace.com/u/noel_david)\
**Post date:** [November 21, 2024, 8:11am UTC](https://community.dynatrace.com/t/general-oneagent-update-issues-and-troubleshooting/48997/1 "2024-11-21T08:11:35Z")

</div>

## Summary

This article covers the most common failure scenarios encountered during a **Dynatrace OneAgent update** on both **Linux and Windows** hosts. It is intended to help diagnose why a OneAgent update may be failing and guide you through the appropriate resolution steps for each scenario.

OneAgent has a built-in, configurable auto-update mechanism. When an update is triggered&nbsp; either automatically or manually the agent initiates its own update cycle, downloads the installer, and runs it locally. Most updates complete within **5–20 minutes** under normal conditions. When updates fail, the cause is typically related to system-level conditions on the host rather than Dynatrace itself.

## Problem

OneAgent update fails and one or more of the following symptoms are observed:

**On Windows:**

- The update fails with **MSI error code 1603**

- The installer log references a **missing MSI package** in the Windows Installer Cache with errors such as:

**On Linux:**

- The OS logs contain the following warning:

- The update fails with an error indicating the **filesystem is read-only**

- The update fails due to **insufficient disk space**

- The update fails with no specific error the agent disappears from the UI or shows **“installation aborted”**

**In the Dynatrace UI (Linux and Windows):**

- The Deployment Status page shows: **“Automatic update problem – Unresolved problem with OneAgent version installation attempt”**
- **Daily failure notifications** appear in System Notifications even after automatic updates are disabled in the UI
- The update status shows **“Update problem”** with no additional detail visible

_._

## Troubleshooting steps

### Step 1 Check the Installer Logs

All update-related activity is logged in the installer log directory. Review these first to identify a specific error message.

- **Linux:** `<oneagent_install_path>/logs/installer/`
  - To monitor in real time:

- **Windows:** `C:\ProgramData\dynatrace\oneagent\log\installer\installation_msiexec_*.log`

* * *

### Step 2 Run the OneAgent Health Check

On both Linux and Windows, run the built-in health check to surface specific conditions blocking the update:

```bash
./oneagentctl --healthcheck

```

This will report issues such as insufficient disk space, permission problems, read-only filesystem, or misconfiguration in the agent’s own configuration file.

* * *

### Step 3 Verify System Requirements

Confirm the host meets all minimum requirements before retrying:

| Requirement | Minimum |
| --- | --- |
| Free disk space | Sufficient space in the OneAgent installation path |
| Free memory | **200 MB** &nbsp;minimum |
| Installation path | Must be a&nbsp; **real directory** &nbsp;not a symbolic link (Linux) |
| Filesystem | Must be&nbsp; **writable** &nbsp;and not mounted as read-only |

- **Check disk space (Linux):**

- **Check mount options (Linux):**

* * *

### Step 4 Identify the Specific Scenario

Use the table below to match your symptoms to the relevant resolution:

| Symptom | Platform | Go to Resolution |
| --- | --- | --- |
| MSI error 1603 | Windows | Scenario A |
| Missing MSI package in Installer Cache | Windows | Scenario B |
| Dangling symlink error | Linux | Scenario C |
| Insufficient disk space | Linux / Windows | Scenario D |
| Generic failure / health check needed | Linux | Scenario E |
| “Automatic update problem” in UI | Linux / Windows | Scenario F |

## Resolution

### Scenario A MSI Error 1603 (Windows)

This is a **Microsoft Windows Installer error** , not a Dynatrace-specific issue. It can be caused by permission problems, antivirus interference, locked files, or a corrupted Windows Installer state.

**Steps:**

1. Review the installer log at: `C:\ProgramData\dynatrace\oneagent\log\installer\installation_msiexec_*.log`
2. Check for interference from antivirus or endpoint security tools (e.g., McAfee ENS). If present, temporarily disable **Self-Protection** and **Exploit Prevention** during the update.
3. For further guidance on the Windows-side error, refer to: [MSI installation error 1603 – Windows Server | Microsoft Learn](https://learn.microsoft.com/en-us/troubleshoot/windows-server/application-management/msiexec-error-1603)

* * *

### Scenario B Missing MSI Package in Windows Installer Cache (Windows)

The Windows Installer Cache (`C:\Windows\Installer`) stores files required for uninstalling and updating installed products. If the cached MSI for the currently installed OneAgent version is missing, the update cannot remove the old version.

**Steps:**

1. Identify the missing MSI filename from the installer log (e.g., `312c0.msi`).
2. Download and unpack the MSI package from the installer of the **currently installed** OneAgent version by following the [Get MSI Package](https://docs.dynatrace.com/docs/shortlink/oneagent-windows-install#msi) instructions.
3. Copy the extracted MSI to `C:\Windows\Installer` and rename it to match the filename referenced in the log.
4. Retry the OneAgent update.

* * *

### Scenario C Dangling Symlink Blocking Update (Linux)

OneAgent requires its installation path to be a **real directory**. A symbolic link especially a dangling one (pointing to a non-existent target) is not supported and will cause the update to fail.

**Steps:**

1. Confirm the symlink:

2. Remove the dangling symlink:

3. Create the real directory:

4. Retry the OneAgent update.

* * *

### Scenario D Insufficient Disk Space (Linux / Windows)

**Steps:**

1. Check available disk space:

2. Free up space by removing unnecessary files, old logs, or temporary data.

3. Ensure the host also has at least **200 MB of free memory** available.

4. Retry the update once both conditions are met.

5. As a long-term fix, consider relocating the OneAgent installation to a partition with more available space using the `INSTALL_PATH` parameter during reinstallation.

* * *

### Scenario E Generic Update Failure / Health Check Required (Linux)

When no specific error is immediately visible, the health check output will identify the root cause. Common findings and their resolutions are:

| Finding | Resolution |
| --- | --- |
| **Read-only filesystem** | Check&nbsp;`dmesg`&nbsp;for I/O errors. Remount the filesystem as read-write or fix the underlying issue. |
| **Security tool interference** &nbsp;(CrowdStrike, SELinux enforcing) | Temporarily exclude the OneAgent installation path from endpoint security scanning, or configure the appropriate SELinux boolean. |
| **NFS-based installation path** | OneAgent is not stable on NFS. Reinstall to a local path using the&nbsp;`INSTALL_PATH`&nbsp;parameter. FUSE filesystems are not supported. |
| **Empty&nbsp;`LogDir`&nbsp;in agent config** | Locate the OneAgent configuration file, populate the empty&nbsp;`LogDir`&nbsp;value, and retry the installation. |
| **Residual files from a failed install** | Run a clean uninstall, remove residual files, and reinstall: |

**Clean uninstall and reinstall (Linux):**

```bash
# Run the bundled uninstall script
/opt/dynatrace/oneagent/agent/uninstall.sh

# Remove residual state
rm -rf /var/lib/dynatrace/oneagent

# Then perform a fresh installation

```

Reference: [Uninstall OneAgent on Linux](https://docs.dynatrace.com/docs/ingest-from/dynatrace-oneagent/installation-and-operation/linux/operation/uninstall-oneagent-on-linux)

* * *

### Scenario F&nbsp; “Automatic Update Problem” Shown in UI (Linux / Windows)

**Steps:**

1. Go to **Deployment Status** and manually trigger an update on the affected host using **Update now**.
2. Review the installer logs for a specific error and apply the relevant resolution from this article.
3. If the current OneAgent version is several major versions behind the target, there may be **no direct upgrade path**. In this case, upgrade through intermediate versions sequentially before targeting the latest release.
4. If the host is stuck and blocking the update rollout to other hosts, collect a diagnostics archive and contact Dynatrace Support (see [What’s Next](https://assistant.d1.dynatrace.com/assistant#whats-next)).

* * *

## What’s next

If the steps in this article did not resolve the issue, please **open a Dynatrace Support ticket** and include the following:

- A note that this article was followed and which scenario most closely matched

- The **OneAgent version** currently installed and the **target version** being updated to

- The **operating system** and version of the affected host(s)

- The **installer log files** from the host:

- A **OneAgent support archive** , collected via:

- A **screenshot** of the error message shown in the Dynatrace UI (if applicable)

### 

Related reading

📖&nbsp;[OneAgent Troubleshooting documentation](https://docs.dynatrace.com/docs/ingest-from/dynatrace-oneagent/oneagent-troubleshooting/troubleshoot-oneagent-installation).

---

<div class="post-metadata">

**Author:** ![paolo\_fumanelli](https://dub1.discourse-cdn.com/dynatrace/user_avatar/community.dynatrace.com/paolo_fumanelli/32/1037_2.png) [@paolo\_fumanelli](https://community.dynatrace.com/u/paolo_fumanelli)\
**Post date:** [May 27, 2025, 8:32am UTC](https://community.dynatrace.com/t/general-oneagent-update-issues-and-troubleshooting/48997/2 "2025-05-27T08:32:19Z")

</div>

Hi, about scenario 3, how can we check in advance if a host has sufficient disk space?

My idea is to run a check 2 weeks before oneagents update to detect hosts on which to increase disk space when it is insufficient.

Thanks

---

<div class="post-metadata">

**Author:** ![noel\_david](https://avatars.discourse-cdn.com/v4/letter/n/3ec8ea/32.png) [@noel\_david](https://community.dynatrace.com/u/noel_david)\
**Post date:** [May 28, 2025, 5:45am UTC](https://community.dynatrace.com/t/general-oneagent-update-issues-and-troubleshooting/48997/3 "2025-05-28T05:45:38Z")

</div>

Hi Paolo,

The logic of checking if there are enough spaces is invoked during the update/installation step. As of now, it’s not possible to check the disk space in advance.

But this page will be helpful.

> **[OneAgent files and disk space requirements on Windows](https://docs.dynatrace.com/docs/ingest-from/dynatrace-oneagent/installation-and-operation/windows/installation/disk-space-requirements-for-oneagent-installation-and-update-on-windows)**
>
> Learn the OneAgent directory structure and disk space requirements for OneAgent installation on Windows.
