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 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:
Warning: Local cached package 'C:\Windows\Installer\312c0.msi' is missing. Error 1714. The older version of Dynatrace OneAgent cannot be removed. System Error 1612.
On Linux:
-
The OS logs contain the following warning:
Error: Detected that /opt/dynatrace/oneagent is a dangling symlink, please remove it and then retry the installation. -
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:
tail -f <oneagent_install_path>/logs/installer/*
-
- 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:
./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 minimum |
| Installation path | Must be a real directory not a symbolic link (Linux) |
| Filesystem | Must be writable and not mounted as read-only |
-
Check disk space (Linux):
df -h /opt/dynatrace -
Check mount options (Linux):
mount | grep <partition> dmesg | grep -i "read-only"
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:
- Review the installer log at:
C:\ProgramData\dynatrace\oneagent\log\installer\installation_msiexec_*.log - 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.
- For further guidance on the Windows-side error, refer to: MSI installation error 1603 – Windows Server | Microsoft Learn
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:
- Identify the missing MSI filename from the installer log (e.g.,
312c0.msi). - Download and unpack the MSI package from the installer of the currently installed OneAgent version by following the Get MSI Package instructions.
- Copy the extracted MSI to
C:\Windows\Installerand rename it to match the filename referenced in the log. - 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:
-
Confirm the symlink:
ls -la /opt/dynatrace/oneagent -
Remove the dangling symlink:
rm /opt/dynatrace/oneagent -
Create the real directory:
mkdir -p /opt/dynatrace/oneagent -
Retry the OneAgent update.
Scenario D Insufficient Disk Space (Linux / Windows)
Steps:
-
Check available disk space:
# Linux df -h /opt/dynatrace -
Free up space by removing unnecessary files, old logs, or temporary data.
-
Ensure the host also has at least 200 MB of free memory available.
-
Retry the update once both conditions are met.
-
As a long-term fix, consider relocating the OneAgent installation to a partition with more available space using the
INSTALL_PATHparameter 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 dmesg for I/O errors. Remount the filesystem as read-write or fix the underlying issue. |
| Security tool interference (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 INSTALL_PATH parameter. FUSE filesystems are not supported. |
Empty LogDir in agent config |
Locate the OneAgent configuration file, populate the empty LogDir 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):
# 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
Scenario F “Automatic Update Problem” Shown in UI (Linux / Windows)
Steps:
- Go to Deployment Status and manually trigger an update on the affected host using Update now.
- Review the installer logs for a specific error and apply the relevant resolution from this article.
- 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.
- 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).
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:
- Linux:
<oneagent_install_path>/logs/installer/ - Windows:
C:\ProgramData\dynatrace\oneagent\log\installer\
- Linux:
-
A OneAgent support archive, collected via:
./oneagentctl --create-support-archiveOr via the Dynatrace UI: Host page → (…) menu → OneAgent Diagnostics
-
A screenshot of the error message shown in the Dynatrace UI (if applicable)
Related reading