Troubleshooting
Troubleshooting should establish what actually happened before another operation changes the system state. Have the affected Host, Pool, VM and Task identifiers, the installed release and a timestamp. Keep a Host console available when management connectivity is broken. The objective is to recover the intended service without duplicating work or losing data.
Establish the current state
From an authorized Host shell, inspect services, Xen and networking:
rc-status
rc-service xapi status
rc-service hv-agent status
rc-service hv status
xl info
ip address
ip route
hv-upgrade statusFrom the configured CLI, inspect hv task show TASK_ID and the current VM or Host. Use CLI and API to select the correct database or server. If a request lost its response, inspect its Task and resulting objects before repeating it.
Resolve common symptoms
| Symptom | Check and next action |
|---|---|
| No installer interview | Confirm UEFI boot and open tty1; serial output may show only logs. Do not start a concurrent installer. |
| Dashboard unavailable | Check the profile's administration port, management address, route, hv-agent and hv. Public normally uses 8443. |
| Local Pool absent | Check xapi and first-boot service diagnostics; allow bootstrap to finish before registering duplicate connections. |
| Sign-in rejected repeatedly | Review input, clock and policy; wait for rate limits instead of repeatedly resubmitting. |
| Empty resource selector | Check the acting Silo, Project ownership and infrastructure visibility. |
| VM created but not running | Inspect that VM's start error, firmware and boot image. BIOS VM boot is not a working supported path today. |
| Console fails | Verify VM power, console rights, trusted agent connection and WebSocket proxying. Open a fresh session. |
| No guest memory | Check guest tools; allocated RAM is not observed operating-system usage. |
| Backup or import remains queued | Confirm an execution engine is running on the intended database and inspect the Task. |
| Maintenance stops | The Host may already be disabled. Inspect remaining VMs, destination memory, SRs and Networks before reboot. |
| Update fails | Inspect rolling-update step, Host slots and service health; correct the cause before Resume. |
Recover connectivity and boot
Use the Host console to inspect actual interface and bridge state. xapi and xcp-networkd own management networking; do not move the address to a physical NIC behind their backs. A public /32 needs the provider gateway route. Mesh-management installations have a different management PIF and refuse ordinary console address editing.
PVH boot failures can fall back to PV after reboot. Check the recorded fallback and IOMMU state. A hung dom0 may need out-of-band recovery; the fallback does not guarantee an automatic reset. Root rollback preserves shared state and therefore cannot undo all management changes.
Keep diagnostic records
Read logs and record the exact diagnostic and failing step. Share sanitized excerpts, never setup tokens, API bearer values, answer files or private key material. Include controller/NIC models and boot-console output for hardware failures.
Do not delete parent backup files, format SRs or clear live locks as exploratory repairs. Inspect partially created restore objects and promoted Replicas before retrying recovery. Once repaired, verify both the management state and the application's actual behavior, then record the outcome for the next administrator.