Vendor-neutral Windows agent upgrade triage

Preserve the failure before you retry the upgrade.

A repeated reinstall can erase the evidence that separates a damaged package from a pending reboot, concurrent installer, file lock, blocked service, security-control decision, proxy failure, or an unsupported upgrade path. Use these 24 checks to diagnose one representative endpoint before changing the fleet.

Download the evidence CSVTroubleshoot missing check-insTroubleshoot high resource useVerify agent removalInstallation troubleshooting guidePrint this checklist

1. Scope and preserve

  1. Confirm the process, service, package, publisher, source, target version, tenant, and endpoint are the approved agent upgrade—not a similarly named or stale component.
  2. Record the affected customer, site, device cohort, current and target versions, deployment policy, first failure time, maintenance window, business impact, and change authority.
  3. Preserve the original status, exact command line, exit code, timestamps, console message, local logs, and event records before another retry overwrites or rotates them.
  4. Separate one-device failure from a shared cohort by operating system, architecture, current version, policy, network, security stack, update ring, and deployment time.

2. Verify package and prerequisites

  1. Validate the package source, expected filename, digital signature, publisher, version, hash when supplied, and complete download before execution.
  2. Check supported operating system and architecture, free system-drive space, endpoint clock, pending restart state, and prerequisite runtime or service requirements.
  3. Confirm the upgrade runs in the intended account and session with the required local rights, service-control access, filesystem access, and application-control policy.
  4. Test the documented DNS, proxy, TLS, certificate, and outbound path to the vendor's update source without broadly bypassing filtering or inspection.

3. Read installer evidence

  1. Capture the exact installer technology, command, switches, working directory, start and end times, process tree, exit code, and any reboot-required result.
  2. When the package uses Windows Installer, collect a bounded verbose log through the vendor-supported command or documented /log option; do not enable indefinite fleet-wide logging.
  3. Correlate the installer log with Windows Installer and Application event records, agent updater logs, service-control events, and the deployment platform's result.
  4. Interpret codes in context: distinguish another installation in progress, inaccessible or invalid package, logging failure, rollback, reboot required, and vendor-defined results rather than labeling every nonzero code the same.

4. Isolate conflicts and state

  1. Inspect the agent, updater, helper, and remote-access services and processes for stopped, hung, crash-looping, or version-mismatched state.
  2. Check for concurrent installers, file or registry locks, Restart Manager activity, pending file replacement, and a restart that the approved workflow has not completed.
  3. Review EDR, antivirus, application control, exploit protection, and content-filter events for the exact signer, hash, path, process, or connection involved; do not infer a block from absence alone.
  4. Compare the local package cache, staging directory, configuration, and updater metadata with a healthy peer; preserve evidence before clearing stale or incomplete state.

5. Repair one pilot safely

  1. Define success, rollback, stop condition, evidence retention, owner, and escalation route before changing a representative endpoint.
  2. Correct the narrow verified cause—prerequisite, reboot, permission, path, proxy, damaged download, blocked signed component, or supported version sequence—without weakening fleet-wide controls.
  3. Use the vendor-supported repair, re-download, cleanup, or staged-upgrade path on one authorized pilot; avoid repeated uninstall/reinstall loops that destroy identity and evidence.
  4. Retest once under a comparable policy and maintenance window, recording new logs, exit code, duration, service state, installed version, and rollback behavior.

6. Validate and close

  1. Verify the installed version, publisher signature, service path, tenant and device identity, update-policy assignment, and successful platform check-in.
  2. Test inventory, monitoring, alerting, one bounded script, patch scan, and remote support separately so a version number is not mistaken for a healthy agent.
  3. Reconcile every targeted endpoint into upgraded, unaffected, deferred, failed, rolled back, retired, duplicate, unsupported, or time-bounded-exception states.
  4. Record root cause, affected versions or policies, corrective and preventive action, rollout decision, residual risk, exception expiry, owner, customer communication, and closure evidence.

When is an agent upgrade actually resolved?

Resolution requires more than a successful installer return. The intended signed version must be installed under the correct tenant and device identity, privileged agent functions must pass, the targeted cohort must be reconciled, and every failure, deferral, rollback, unsupported device, or exception must have an owner and next action. If the installer succeeded but the endpoint stopped checking in, continue with the offline-agent checklist; if the recovery path is unclear, use the repair vs reinstall decision matrix.

Primary references and interpretation limits