Skip to main content

Repair the XOA updater

VKB-1001Troubleshooting
📦 Applies to
Xen Orchestra
🗓️ Created
2024-05-16
🔄 Updated
2026-08-05
🏷️ Tags
#xoa#updater#xoa-cli#proxy

Symptoms​

  • xoa commands do not respond on the appliance console.
  • Updates fail or stay stuck in the web interface, sometimes with SSL or TLS errors in the updater log.
  • Packages are missing after a failed build or a manual error.

Environment​

  • Xen Orchestra Appliance (XOA), any version.
  • Does not apply to Xen Orchestra built from the sources.

Diagnosis​

Connect to the appliance over SSH and run the built-in health check as root. The failing area is reported in the checklist:

root@xoa — xoa check
# xoa check
✓ Node version
✓ Disk space
✓ XOA version
✓ DNS resolution
✗ Access to updates.xen-orchestra.com
✓ Internet connectivity

A failure on the updater endpoint while internet connectivity works usually points at stale updater state, or at a transparent proxy intercepting TLS.

Cause​

The updater keeps its state in /var/lib/xoa-updater/update.json. A failed build or an interrupted update can leave that state inconsistent, after which xoa commands hang. Separately, a transparent proxy that re-signs TLS makes the updater reject the connection to the update servers.

Resolution​

Force the updater to redownload packages​

root@xoa
# rm /var/lib/xoa-updater/update.json
# xoa-updater --upgrade

Updater behind a transparent proxy​

root@xoa
# echo NODE_TLS_REJECT_UNAUTHORIZED=0 >> /etc/xo-appliance/env
# npm config -g set strict-ssl=false
# systemctl restart xoa-updater

Then retry the update from the web interface or with xoa-updater --upgrade.

If the issue persists, open a support ticket (VKB-1003) and attach the output of xoa check.

Related articles