https://community.dynatrace.com/t5/Troubleshooting/General-Oneagent-update-Issues-and-troubleshooting/ta-p/263154 <P><LI-TOC indent="15" liststyle="disc" maxheadinglevel="2"></LI-TOC></P> <H2>Summary</H2> <P>&nbsp;</P> <P>This article covers the most common failure scenarios encountered during a <STRONG>Dynatrace OneAgent update</STRONG> on both <STRONG>Linux and Windows</STRONG> 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.</P> <P>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 <STRONG>5–20 minutes</STRONG> under normal conditions. When updates fail, the cause is typically related to system-level conditions on the host rather than Dynatrace itself.</P> <P>&nbsp;</P> <H2>Problem</H2> <P>&nbsp;</P> <P>OneAgent update fails and one or more of the following symptoms are observed:</P> <P><STRONG>On Windows:</STRONG></P> <UL> <LI>The update fails with <STRONG>MSI error code 1603</STRONG></LI> <LI>The installer log references a <STRONG>missing MSI package</STRONG> in the Windows Installer Cache with errors such as: <PRE><CODE>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. </CODE></PRE> </LI> </UL> <P><STRONG>On Linux:</STRONG></P> <UL> <LI>The OS logs contain the following warning: <PRE><CODE>Error: Detected that /opt/dynatrace/oneagent is a dangling symlink, please remove it and then retry the installation. </CODE></PRE> </LI> <LI>The update fails with an error indicating the <STRONG>filesystem is read-only</STRONG></LI> <LI>The update fails due to <STRONG>insufficient disk space</STRONG></LI> <LI>The update fails with no specific error the agent disappears from the UI or shows <STRONG>"installation aborted"</STRONG></LI> </UL> <P><STRONG>In the Dynatrace UI (Linux and Windows):</STRONG></P> <UL> <LI>The Deployment Status page shows: <STRONG>"Automatic update problem – Unresolved problem with OneAgent version installation attempt"</STRONG></LI> <LI><STRONG>Daily failure notifications</STRONG> appear in System Notifications even after automatic updates are disabled in the UI</LI> <LI>The update status shows <STRONG>"Update problem"</STRONG> with no additional detail visible</LI> </UL> <P><EM>.</EM></P> <P>&nbsp;</P> <H2>Troubleshooting steps</H2> <P>&nbsp;</P> <H3>Step 1 Check the Installer Logs</H3> <P>All update-related activity is logged in the installer log directory. Review these first to identify a specific error message.</P> <UL> <LI><STRONG>Linux:</STRONG> <CODE>&lt;oneagent_install_path&gt;/logs/installer/</CODE> <UL> <LI>To monitor in real time: <PRE><CODE class="language-bash">tail -f &lt;oneagent_install_path&gt;/logs/installer/* </CODE></PRE> </LI> </UL> </LI> <LI><STRONG>Windows:</STRONG> <CODE>C:\ProgramData\dynatrace\oneagent\log\installer\installation_msiexec_*.log</CODE></LI> </UL> <HR /> <H3>Step 2 Run the OneAgent Health Check</H3> <P>On both Linux and Windows, run the built-in health check to surface specific conditions blocking the update:</P> <PRE><CODE class="language-bash">./oneagentctl --healthcheck </CODE></PRE> <P>This will report issues such as insufficient disk space, permission problems, read-only filesystem, or misconfiguration in the agent's own configuration file.</P> <HR /> <H3>Step 3 Verify System Requirements</H3> <P>Confirm the host meets all minimum requirements before retrying:</P> <TABLE> <THEAD> <TR> <TH class="lia-align-center"><FONT size="2">Requirement</FONT></TH> <TH class="lia-align-center"><FONT size="2">Minimum</FONT></TH> </TR> </THEAD> <TBODY> <TR> <TD>Free disk space</TD> <TD>Sufficient space in the OneAgent installation path</TD> </TR> <TR> <TD>Free memory</TD> <TD><STRONG>200 MB</STRONG><SPAN>&nbsp;</SPAN>minimum</TD> </TR> <TR> <TD>Installation path</TD> <TD>Must be a<SPAN>&nbsp;</SPAN><STRONG>real directory</STRONG><SPAN>&nbsp;</SPAN>not a symbolic link (Linux)</TD> </TR> <TR> <TD>Filesystem</TD> <TD>Must be<SPAN>&nbsp;</SPAN><STRONG>writable</STRONG><SPAN>&nbsp;</SPAN>and not mounted as read-only</TD> </TR> </TBODY> </TABLE> <UL> <LI><STRONG>Check disk space (Linux):</STRONG> <PRE><CODE class="language-bash">df -h /opt/dynatrace </CODE></PRE> </LI> <LI><STRONG>Check mount options (Linux):</STRONG> <PRE><CODE class="language-bash">mount | grep &lt;partition&gt; dmesg | grep -i "read-only" </CODE></PRE> </LI> </UL> <HR /> <H3>Step 4 Identify the Specific Scenario</H3> <P>Use the table below to match your symptoms to the relevant resolution:</P> <TABLE width="514px"> <THEAD> <TR> <TH class="lia-align-center" width="283.281px"><FONT size="2">Symptom</FONT></TH> <TH class="lia-align-center" width="128.797px"><FONT size="2">Platform</FONT></TH> <TH class="lia-align-center" width="100.922px"><FONT size="2">Go to Resolution</FONT></TH> </TR> </THEAD> <TBODY> <TR> <TD width="283.281px">MSI error 1603</TD> <TD width="128.797px">Windows</TD> <TD width="100.922px">Scenario A</TD> </TR> <TR> <TD width="283.281px">Missing MSI package in Installer Cache</TD> <TD width="128.797px">Windows</TD> <TD width="100.922px">Scenario B</TD> </TR> <TR> <TD width="283.281px">Dangling symlink error</TD> <TD width="128.797px">Linux</TD> <TD width="100.922px">Scenario C</TD> </TR> <TR> <TD width="283.281px">Insufficient disk space</TD> <TD width="128.797px">Linux / Windows</TD> <TD width="100.922px">Scenario D</TD> </TR> <TR> <TD width="283.281px">Generic failure / health check needed</TD> <TD width="128.797px">Linux</TD> <TD width="100.922px">Scenario E</TD> </TR> <TR> <TD width="283.281px">"Automatic update problem" in UI</TD> <TD width="128.797px">Linux / Windows</TD> <TD width="100.922px">Scenario F</TD> </TR> </TBODY> </TABLE> <P>&nbsp;</P> <P>&nbsp;</P> <H2>Resolution</H2> <H3>Scenario A MSI Error 1603 (Windows)</H3> <P>This is a <STRONG>Microsoft Windows Installer error</STRONG>, not a Dynatrace-specific issue. It can be caused by permission problems, antivirus interference, locked files, or a corrupted Windows Installer state.</P> <P><STRONG>Steps:</STRONG></P> <OL> <LI>Review the installer log at: <CODE>C:\ProgramData\dynatrace\oneagent\log\installer\installation_msiexec_*.log</CODE></LI> <LI>Check for interference from antivirus or endpoint security tools (e.g., McAfee ENS). If present, temporarily disable <STRONG>Self-Protection</STRONG> and <STRONG>Exploit Prevention</STRONG> during the update.</LI> <LI>For further guidance on the Windows-side error, refer to: <A href="https://learn.microsoft.com/en-us/troubleshoot/windows-server/application-management/msiexec-error-1603" target="_blank" rel="noopener">MSI installation error 1603 – Windows Server | Microsoft Learn</A></LI> </OL> <HR /> <H3>Scenario B Missing MSI Package in Windows Installer Cache (Windows)</H3> <P>The Windows Installer Cache (<CODE>C:\Windows\Installer</CODE>) 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.</P> <P><STRONG>Steps:</STRONG></P> <OL> <LI>Identify the missing MSI filename from the installer log (e.g., <CODE>312c0.msi</CODE>).</LI> <LI>Download and unpack the MSI package from the installer of the <STRONG>currently installed</STRONG> OneAgent version by following the <A href="https://docs.dynatrace.com/docs/shortlink/oneagent-windows-install#msi" target="_blank" rel="noopener">Get MSI Package</A> instructions.</LI> <LI>Copy the extracted MSI to <CODE>C:\Windows\Installer</CODE> and rename it to match the filename referenced in the log.</LI> <LI>Retry the OneAgent update.</LI> </OL> <HR /> <H3>Scenario C Dangling Symlink Blocking Update (Linux)</H3> <P>OneAgent requires its installation path to be a <STRONG>real directory</STRONG>. A symbolic link especially a dangling one (pointing to a non-existent target) is not supported and will cause the update to fail.</P> <P><STRONG>Steps:</STRONG></P> <OL> <LI>Confirm the symlink: <PRE><CODE class="language-bash">ls -la /opt/dynatrace/oneagent </CODE></PRE> </LI> <LI>Remove the dangling symlink: <PRE><CODE class="language-bash">rm /opt/dynatrace/oneagent </CODE></PRE> </LI> <LI>Create the real directory: <PRE><CODE class="language-bash">mkdir -p /opt/dynatrace/oneagent </CODE></PRE> </LI> <LI>Retry the OneAgent update.</LI> </OL> <HR /> <H3>Scenario D Insufficient Disk Space (Linux / Windows)</H3> <P><STRONG>Steps:</STRONG></P> <OL> <LI>Check available disk space: <PRE><CODE class="language-bash"># Linux df -h /opt/dynatrace </CODE></PRE> </LI> <LI>Free up space by removing unnecessary files, old logs, or temporary data.</LI> <LI>Ensure the host also has at least <STRONG>200 MB of free memory</STRONG> available.</LI> <LI>Retry the update once both conditions are met.</LI> <LI>As a long-term fix, consider relocating the OneAgent installation to a partition with more available space using the <CODE>INSTALL_PATH</CODE> parameter during reinstallation.</LI> </OL> <HR /> <H3>Scenario E Generic Update Failure / Health Check Required (Linux)</H3> <P>When no specific error is immediately visible, the health check output will identify the root cause. Common findings and their resolutions are:</P> <TABLE> <THEAD> <TR> <TH>Finding</TH> <TH>Resolution</TH> </TR> </THEAD> <TBODY> <TR> <TD><STRONG>Read-only filesystem</STRONG></TD> <TD>Check<SPAN>&nbsp;</SPAN><CODE>dmesg</CODE><SPAN>&nbsp;</SPAN>for I/O errors. Remount the filesystem as read-write or fix the underlying issue.</TD> </TR> <TR> <TD><STRONG>Security tool interference</STRONG><SPAN>&nbsp;</SPAN>(CrowdStrike, SELinux enforcing)</TD> <TD>Temporarily exclude the OneAgent installation path from endpoint security scanning, or configure the appropriate SELinux boolean.</TD> </TR> <TR> <TD><STRONG>NFS-based installation path</STRONG></TD> <TD>OneAgent is not stable on NFS. Reinstall to a local path using the<SPAN>&nbsp;</SPAN><CODE>INSTALL_PATH</CODE><SPAN>&nbsp;</SPAN>parameter. FUSE filesystems are not supported.</TD> </TR> <TR> <TD><STRONG>Empty<SPAN>&nbsp;</SPAN><CODE>LogDir</CODE><SPAN>&nbsp;</SPAN>in agent config</STRONG></TD> <TD>Locate the OneAgent configuration file, populate the empty<SPAN>&nbsp;</SPAN><CODE>LogDir</CODE><SPAN>&nbsp;</SPAN>value, and retry the installation.</TD> </TR> <TR> <TD><STRONG>Residual files from a failed install</STRONG></TD> <TD>Run a clean uninstall, remove residual files, and reinstall:</TD> </TR> </TBODY> </TABLE> <P><STRONG>Clean uninstall and reinstall (Linux):</STRONG></P> <PRE><CODE class="language-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 </CODE></PRE> <P>Reference: <A href="https://docs.dynatrace.com/docs/ingest-from/dynatrace-oneagent/installation-and-operation/linux/operation/uninstall-oneagent-on-linux" target="_blank" rel="noopener">Uninstall OneAgent on Linux</A></P> <HR /> <H3>Scenario F&nbsp; "Automatic Update Problem" Shown in UI (Linux / Windows)</H3> <P><STRONG>Steps:</STRONG></P> <OL> <LI>Go to <STRONG>Deployment Status</STRONG> and manually trigger an update on the affected host using <STRONG>Update now</STRONG>.</LI> <LI>Review the installer logs for a specific error and apply the relevant resolution from this article.</LI> <LI>If the current OneAgent version is several major versions behind the target, there may be <STRONG>no direct upgrade path</STRONG>. In this case, upgrade through intermediate versions sequentially before targeting the latest release.</LI> <LI>If the host is stuck and blocking the update rollout to other hosts, collect a diagnostics archive and contact Dynatrace Support (see <A href="https://assistant.d1.dynatrace.com/assistant#whats-next" target="_blank" rel="noopener">What's Next</A>).</LI> </OL> <HR /> <P>&nbsp;</P> <H2>What's next</H2> <P>If the steps in this article did not resolve the issue, please <STRONG>open a Dynatrace Support ticket</STRONG> and include the following:</P> <UL> <LI>A note that this article was followed and which scenario most closely matched</LI> <LI>The <STRONG>OneAgent version</STRONG> currently installed and the <STRONG>target version</STRONG> being updated to</LI> <LI>The <STRONG>operating system</STRONG> and version of the affected host(s)</LI> <LI>The <STRONG>installer log files</STRONG> from the host: <UL> <LI>Linux: <CODE>&lt;oneagent_install_path&gt;/logs/installer/</CODE></LI> <LI>Windows: <CODE>C:\ProgramData\dynatrace\oneagent\log\installer\</CODE></LI> </UL> </LI> <LI>A <STRONG>OneAgent support archive</STRONG>, collected via: <PRE><CODE class="language-bash">./oneagentctl --create-support-archive </CODE></PRE> Or via the Dynatrace UI: <STRONG>Host page → (...) menu → OneAgent Diagnostics</STRONG></LI> <LI>A <STRONG>screenshot</STRONG> of the error message shown in the Dynatrace UI (if applicable)</LI> </UL> <H3><BR />Related reading</H3> <P><SPAN><span class="lia-unicode-emoji" title=":open_book:">📖</span>&nbsp;</SPAN><A href="https://docs.dynatrace.com/docs/ingest-from/dynatrace-oneagent/oneagent-troubleshooting/troubleshoot-oneagent-installation" target="_blank" rel="noopener">OneAgent Troubleshooting documentation</A><SPAN>.</SPAN></P> Tue, 25 Aug 2026 13:37:00 GMT noel_david 2026-08-25T13:37:00Z https://community.dynatrace.com/t5/Troubleshooting/General-Oneagent-update-Issues-and-troubleshooting/ta-p/263154 <P><LI-TOC indent="15" liststyle="disc" maxheadinglevel="2"></LI-TOC></P> <DIV class="lia-message-template-content-zone"> <P>*<EM>Use a table of contents for longer articles.&nbsp;</EM></P> <H2>Summary</H2> <P><EM>*This is a mandatory section.</EM></P> <P><EM>Short description of which part of the Dynatrace platform the article refers to and what kind of problem it will help resolve/ task it will describe.</EM></P> <P>&nbsp;</P> <H2>Problem</H2> <P><EM>*This is a mandatory section.</EM></P> <P><EM>Provide a precise description of the problem/ task to be described. Use anonymized screenshots, and include text for&nbsp;important messages, errors, or information that will help the customer find this article when searching.</EM></P> <P>&nbsp;</P> <H2>Troubleshooting steps</H2> <P><EM>*This section can be omitted as necessary.</EM></P> <P><EM>Explain what troubleshooting steps should be taken to ensure the problem matches this article.</EM></P> <P>&nbsp;</P> <H2>Resolution</H2> <P><EM>*This section can be omitted for articles that guide customers on ticket creation.</EM></P> <P><EM>Explain the solution or all possible solutions resulting from the troubleshooting steps.<BR /><BR /></EM></P> <H2>What's next</H2> <P><EM>*This is a mandatory section. Customers need a way to respond or follow up if they have questions.&nbsp;</EM></P> <P><EM>Explain what to do if the article did not help.&nbsp;</EM><EM>Note that there are multiple options available, including:</EM></P> <OL> <LI><EM><STRONG>Opening a support ticket</STRONG> - be as specific as possible about the information the customer should include in the ticket.&nbsp;</EM> If this article did not help, please open a support ticket, mention that this article was used and provide the following in the ticket: <UL> <LI>link to XYZ</LI> <LI>screenshot of XYZ</LI> <LI>information about XYZ</LI> </UL> </LI> <LI><EM><STRONG>Suggesting Product Idea</STRONG> - encourage the customer to suggest/ vote for a Product Idea explaining their business use case.</EM></LI> <LI><EM><STRONG>Explain this will change in the future</STRONG> - explain that this behaviour will change in a future release. (No product idea / support ticket needed)</EM></LI> <LI><EM><STRONG>Alternatives -</STRONG>&nbsp;any other actions or links to other articles that could move the customer forward.</EM></LI> </OL> <P>&nbsp;</P> <P><EM>*If it exists, link this article to the relevant troubleshooting map using the following guideline</EM></P> <H3>More articles can be found on the <A href="https://community.dynatrace.com/t5/Troubleshooting/" target="_self">XXX Troubleshooting Map</A></H3> </DIV> Tue, 25 Aug 2026 13:37:00 GMT https://community.dynatrace.com/t5/Troubleshooting/General-Oneagent-update-Issues-and-troubleshooting/ta-p/263154 noel_david 2026-08-25T13:37:00Z https://community.dynatrace.com/t5/Troubleshooting/General-Oneagent-update-Issues-and-troubleshooting/tac-p/278058#M911 <P>Hi, about scenario 3, how can we check in advance if a host has sufficient disk space?</P><P>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.</P><P>Thanks</P> Tue, 27 May 2025 08:32:19 GMT https://community.dynatrace.com/t5/Troubleshooting/General-Oneagent-update-Issues-and-troubleshooting/tac-p/278058#M911 paolo_fumanelli 2025-05-27T08:32:19Z https://community.dynatrace.com/t5/Troubleshooting/General-Oneagent-update-Issues-and-troubleshooting/tac-p/278154#M912 <P>Hi Paolo,</P> <P>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.</P> <P>But this page will be helpful.</P> <P><A href="https://docs.dynatrace.com/docs/shortlink/oneagent-disk-requirements-windows#updates" target="_blank">https://docs.dynatrace.com/docs/shortlink/oneagent-disk-requirements-windows#updates</A></P> <P>&nbsp;</P> <P>&nbsp;</P> Wed, 28 May 2025 05:45:38 GMT https://community.dynatrace.com/t5/Troubleshooting/General-Oneagent-update-Issues-and-troubleshooting/tac-p/278154#M912 noel_david 2025-05-28T05:45:38Z