Troubleshooting Guide

Before trying complex fixes, always ensure your system is up to date:

sudo apt update && sudo apt upgrade

Installation Issues

Calamares Installer Fails

If the installer crashes with a "Boost.Python" error:

  • Cause: Often due to an unstable internet connection during installation.
  • Fix: Disconnect from the internet (unplug cable/disable WiFi) and try installing again. You can update the system after installation.

Partitioning Errors

"Not enough space" or EFI errors:

  • Ensure you have disabled Secure Boot and Fast Boot in BIOS.
  • If dual-booting, shrink your Windows partition from Windows first.
  • Create a manual partition table if automatic fails:
    • EFI: 512MB (FAT32, flag: boot/esp)
    • Root (/): Remaining space (BTRFS or EXT4)

Boot Problems

GRUB Rescue / Bootloader Missing

If you can't boot into Soplos after installing Windows or another OS:

  1. Boot from your Soplos Live USB.
  2. Install Boot Repair (if available) or use the terminal.
  3. Terminal Method: 
    sudo mount /dev/sdX2 /mnt  # Your root partition
sudo mount /dev/sdX1 /mnt/boot/efi  # Your EFI partition
sudo grub-install --boot-directory=/mnt/boot --efi-directory=/mnt/boot/efi /dev/sdX

Initramfs Error

If you drop to an (initramfs) prompt, your file system might have errors: 

fsck /dev/sda2 -y

Replace /dev/sda2 with your root partition.

Desktop Environment Specifics

Boro (GNOME)

Boro uses GNOME, which relies heavily on extensions.

Extensions Crashing

If the shell freezes or extensions act up:

# Reset GNOME extensions
dconf reset -f /org/gnome/shell/extensions/

Wayland vs X11

If you have issues with Screen Sharing (Discord, Zoom) or Gaming:

  1. Log out.
  2. Click your user name.
  3. Click the gear icon in the bottom right.
  4. Select "GNOME on Xorg".

Tyron (XFCE)

Panel Missing

If your taskbar disappears:

xfce4-panel -r

Tyson (KDE Plasma)

Reset Configuration

If Plasma becomes unstable:

rm -rf ~/.config/plasma*
kquitapp5 plasmashell && kstart5 plasmashell

Package Management Errors

"Could not get lock"

Error: Could not get lock /var/lib/dpkg/lock

This means another process (like an auto-updater) is using APT. If you are sure nothing is running:

sudo rm /var/lib/apt/lists/lock
sudo rm /var/cache/apt/archives/lock
sudo rm /var/lib/dpkg/lock*
sudo dpkg --configure -a

Broken Packages

If an installation failed halfway:

sudo apt --fix-broken install

Hardware & Network

WiFi Not Detected

  1. Connect via Ethernet or USB Tethering.
  2. Open Soplos Welcome -> Drivers.
  3. Install proprietary drivers (Broadcom, Realtek).

Bluetooth Not Working

Ensure the service is running:

sudo systemctl enable --now bluetooth

If devices don't connect, install blueman for a better manager:

sudo apt install blueman

Printers

Access the CUPS web interface for advanced management:

Graphics & Display

Screen Tearing

  • Boro (GNOME): Usually tear-free on Wayland. On X11, no manual setting is needed.
  • Tyron (XFCE): Window Manager Tweaks -> Compositor -> Enable "Synchronize drawing to the vertical blank".
  • Tyson (Plasma): Display Configuration -> Ensure Refresh Rate is maxed.
  • NVIDIA: Open NVIDIA Settings -> "Force Full Composition Pipeline".