General Oneagent update Issues and troubleshooting

[noel_david]

• Summary
• Problem
• Troubleshooting steps
• Resolution
• What's next

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:

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

---

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 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:

   ls -la /opt/dynatrace/oneagent
   

2. Remove the dangling symlink:

   rm /opt/dynatrace/oneagent
   

3. Create the real directory:

   mkdir -p /opt/dynatrace/oneagent
   

4. Retry the OneAgent update.

---

Scenario D Insufficient Disk Space (Linux / Windows)

Steps:

1. Check available disk space:

   # Linux
   df -h /opt/dynatrace
   

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 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:

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).

---

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\
• A OneAgent support archive, collected via:

  ./oneagentctl --create-support-archive
  

  Or via the Dynatrace UI: Host page → (...) menu → OneAgent Diagnostics
• A screenshot of the error message shown in the Dynatrace UI (if applicable)

Related reading

📖 OneAgent Troubleshooting documentation.

[paolo_fumanelli]

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

[noel_david]

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.

https://docs.dynatrace.com/docs/shortlink/oneagent-disk-requirements-windows#updates