Troubleshooting
Don’t panic when you encounter problems. Based on the symptoms you see, follow the paths below to find the corresponding troubleshooting guide.
If you’re not sure which category your issue falls into, press Ctrl + F to search for keywords, or use the site search at the top of the page.
Cannot Boot / Stuck at Boot Screen
The desktop does not appear after pressing the power button — stuck at a black screen, purple screen, logo, or GRUB menu.
| Symptom | Possible Cause | Troubleshooting Guide |
|---|---|---|
| Completely black screen or only a blinking cursor after boot | Incompatible GPU driver, incorrect kernel parameters | Black Screen |
| Dual boot cannot find Windows/Ubuntu boot entry | GRUB configuration lost, EFI boot corrupted | Dual Boot Repair |
| Stuck at Ubuntu logo | GPU driver loading failed, filesystem corruption | Black Screen |
When encountering boot issues, you can select “Advanced options” from the GRUB menu to boot into an older kernel or recovery mode to restore basic access.
Desktop Loads but Display is Abnormal
You can log in, but the screen flickers, the resolution is wrong, windows are garbled, or multi-monitor is not detected.
| Symptom | Possible Cause | Troubleshooting Guide |
|---|---|---|
| Window dragging causes garbled display or flickering | Wayland incompatibility with GPU/application | Wayland Compatibility |
| Black screen immediately after login or keeps returning to login screen | GPU driver crash, desktop configuration corrupted | Black Screen |
| External monitor has no signal | Port/driver issue | Black Screen |
| Electron apps (VS Code, etc.) display blank | GPU acceleration issue under Wayland | Wayland Compatibility |
No Network / Cannot Connect to Wi-Fi
Wired or wireless network cannot connect, DNS resolution fails, abnormal network speed.
| Symptom | Possible Cause | Troubleshooting Guide |
|---|---|---|
| Wi-Fi list is empty or wireless card not found | Wireless driver missing, hardware switch off | No Network |
| Wired network connected but no internet | DNS configuration error, gateway not set | No Network |
| Can ping IPs but cannot open web pages | DNS resolution failure | No Network |
| Local network unreachable after VPN connection | Routing table conflict | No Network |
No Sound / No Bluetooth Audio
Speakers or headphones have no sound, Bluetooth device cannot connect, or connected but no audio.
| Symptom | Possible Cause | Troubleshooting Guide |
|---|---|---|
| Completely no sound, volume icon appears normal | PipeWire/PulseAudio configuration issue, wrong output device selected | No Sound |
| Bluetooth headset paired successfully but no sound | Audio codec protocol mismatch | Bluetooth Issues |
| Bluetooth device not discoverable or pairing fails | Bluetooth service not started, driver missing | Bluetooth Issues |
| Audio still comes from speakers after plugging in headphones | Audio jack detection failure | No Sound |
Cannot Install Software / Update Errors
apt errors, Snap installation failures, dependency conflicts, permission denied.
| Symptom | Possible Cause | Troubleshooting Guide |
|---|---|---|
apt update reports Hash Sum mismatch or GPG error | Mirror sync issue, expired key | Broken Packages |
| Installing software shows “dependency not satisfied” | PPA version conflict, package held | Broken Packages |
dpkg is locked or interrupted | Previous installation did not complete, multiple package managers running | Broken Packages |
| Command shows Permission denied | sudo not used or user not in sudo group | Permission Issues |
| Snap application fails to start | AppArmor restriction, outdated Snap version | Broken Packages |
Disk Space Full
System shows disk full, cannot write files, or even cannot log in.
| Symptom | Possible Cause | Troubleshooting Guide |
|---|---|---|
| “Disk space full” notification | Log bloat, old Snap versions not cleaned, cache buildup | Disk Space Cleanup |
| Cannot log into desktop (caused by low space) | /home or / partition is full | Disk Space Cleanup |
| Docker consuming large amounts of space | Uncleaned images, containers, and build cache | Disk Space Cleanup |
All Troubleshooting Articles
| Article | Applicable Scenarios |
|---|---|
| Black Screen | Black screen on boot, black screen after login, external monitor no signal |
| Dual Boot Repair | Windows/Ubuntu boot entry missing, GRUB repair |
| Wayland Compatibility | Garbled display, application display issues, what to do when you need an X.org session |
| No Network | Wi-Fi not found, wired not working, DNS issues |
| No Sound | Speaker/headphone no sound, audio device not recognized |
| Bluetooth Issues | Pairing failure, disconnection, Bluetooth audio issues |
| Broken Packages | apt errors, dependency conflicts, dpkg interrupted |
| Permission Issues | Permission denied, sudo configuration, file permissions |
| Disk Space Cleanup | Disk full, log cleanup, Snap/Docker slimming |
If you need to execute destructive commands like rm or dpkg --force during troubleshooting, make sure to create a backup or snapshot first. Mistakes may render the system unbootable.