Diagnosing Talos OS Node Upgrade Failures with talosctl upgrade

Recognizable Condition

After executing talosctl upgrade -n --image , the node reports "upgrade failed" or continues to show the previous version when you run talosctl version on that node.

Cause and Diagnostic Table

Possible Cause	Typical Symptom	Diagnostic Command
Insufficient root filesystem space (<10% free)	Upgrade logs show "no space left on device" or extraction fails	talosctl -n ctr df or ssh df -h /
Network connectivity loss to upgrade server (HTTPS 443 blocked)	Download times out, TLS handshake failure	talosctl -n ctr run --rm alpine wget --timeout=10 --spider https://factory.talos.dev/v1alpha1//talos-amd64.img
Mismatch between talosconfig endpoint and actual API server address	Authentication errors, "unauthorized" or "x509: certificate signed by unknown authority"	talosctl get nodes -o wide and compare talosctl config get endpoints
Corrupted or outdated talosd service state	Service fails to start, upgrade loop, repeated reboot	talosctl -n ctr run --rm alpine ps -eo pid,comm | grep talosd or journalctl -u talosd

Ordered Checks

1. Verify root filesystem free space on the node.
2. Confirm network reachability to the upgrade factory endpoint on port 443.
3. Validate that the talosconfig endpoint matches the node’s advertised API server address.
4. Inspect the talosd service state and recent logs for errors.

Fixes Tied to Findings

Insufficient Root Filesystem Space

Free space by removing unused containers or images, or expand the underlying disk if using a cloud provider. Example cleanup command (run inside the node):

# Inside the node (requires root)
crictl rmi --prune

After freeing space, retry the upgrade:

talosctl upgrade -n  --image 

Network Connectivity Loss

Ensure outbound HTTPS to factory.talos.dev is allowed. Check firewall rules or security groups. Test connectivity:

talosctl -n  ctr run --rm alpine wget --timeout=10 --spider https://factory.talos.dev/v1alpha1//talos-amd64.img

If the test succeeds, re‑run the upgrade.

Talosconfig Endpoint Mismatch

Update talosconfig to point to the correct endpoint:

talosctl config endpoint 
talosctl config merge 

Then retry the upgrade.

Corrupted Talosd Service State
Restart the talosd service on the node:
talosctl -n  ctr run --rm alpine systemctl restart talosd

Check the service status:
talosctl -n  ctr run --rm alpine systemctl status talosd

If the service starts cleanly, retry the upgrade.

Escalation Criteria

After applying the relevant fix, the node still reports upgrade failure.
Logs in journalctl -u talosd show persistent errors such as "failed to extract image" or "segmentation fault".
Multiple nodes exhibit the same symptom despite individual checks.

In these cases, collect the following data for support:

Output of talosctl get nodes -o yaml
Recent journalctl -u talosd logs (last 100 lines)
Output of talosctl version from both control plane and affected node
Details of the underlying platform (bare metal, VM, cloud provider) and disk layout

Open a support ticket with the collected information and reference the Talos OS version you are attempting to upgrade to.