How do I investigate a VPS that stops at a filesystem error during boot?
Use the console to capture the exact boot error, then identify the affected disk and filesystem. Missing storage, an invalid mount entry and actual filesystem damage need different repairs. Do not apply a generic repair command to every visible disk.
Instructions
1. Record the failing stage
Note the error text, affected UUID or device, recent changes and whether the guest enters emergency mode. If you use a rescue ISO, remember that its journal describes the rescue system rather than the failed guest boot.
2. Inspect disks and mounts
Use read-only inventory before selecting any repair target.
lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS
findmnt -o TARGET,SOURCE,FSTYPECheck whether the expected device is attached and whether the affected filesystem is mounted. Device names can change in rescue mode.
3. Choose a filesystem-specific recovery path
For a positively identified, unmounted ext4 filesystem on the example device /dev/vda1, a non-writing check can inform the repair plan.
sudo e2fsck -n /dev/vda1EXT4 EXAMPLE ONLY: run only after identifying the real device and confirming it is unmounted. -n does not approve repairs. Its output is not a valid diagnosis of an actively mounted filesystem.
Check the result
- The actual failed device and filesystem are identified.
- A documented repair restores normal boot and application data checks pass afterward.
Troubleshooting
- The expected disk is absent
- Resolve provider attachment or virtual-controller issues before attempting filesystem repair.
- The filesystem is XFS, encrypted or layered through LVM
- Use the correct layered and filesystem-specific recovery procedure; e2fsck is not a universal checker.
Official references
Use the documentation for your installed version when a flag, service name or platform feature differs.