Quick Navigation
Boot and Update Issues
System fails to boot after update
Boot into previous deployment
- At the GRUB menu, select the previous deployment
- Once booted, run the rollback command:
sudo bootc rollback
sudo systemctl reboot
The rollback makes the previous version permanent until the next update.
Bootc fails with signature verification errors
Install the correct signing keys
# Download the public key
sudo mkdir -p /etc/pki/containers
sudo curl -L https://github.com/soltros/Soltros-OS/raw/main/soltros.pub \
-o /etc/pki/containers/soltros.pub
# Download the secure policy
sudo mkdir -p /etc/containers
sudo curl -L https://github.com/soltros/Soltros-OS/raw/main/resources/policy.json \
-o /etc/containers/policy.json
# Verify permissions
sudo chmod 644 /etc/pki/containers/soltros.pub
sudo chmod 644 /etc/containers/policy.json
System update hangs indefinitely
Cancel and retry with helper
- Press Ctrl+C to cancel the operation
- Try updating again:
helper update
If still stuck, check your internet connection:
ping -c 4 8.8.8.8
Disk Space Issues
Disk full errors, can't install updates
Clean up old deployments and cached files
# Clean old bootc deployments
helper clean
# Clean Flatpak unused runtimes
flatpak uninstall --unused
# Clean Podman/Docker
podman system prune -a
# Clean Nix
nix-collect-garbage -d
# Clean Homebrew
brew cleanup --prune=all
Package Manager Issues
Flatpak install fails or apps won't start
Update and repair Flatpak
# Update Flatpak
flatpak update
# Repair Flatpak installation
flatpak repair --user
# Re-add Flathub repository
flatpak remote-add --if-not-exists flathub \
https://flathub.org/repo/flathub.flatpakrepo
Nix commands fail or nixmanager not found
Update Nix and verify installation
# Update Nix channels
nix-channel --update
# Repair Nix store
nix-store --verify --check-contents
# If nixmanager not found (Bash users)
helper add-nixmanager
# Reinstall Nix if completely broken
sudo rm -rf /nix
helper install-nix
helper setup-nixmanager
Brew commands fail or packages won't install
Diagnose and update Homebrew
# Diagnose issues
brew doctor
# Update Homebrew
brew update
If completely broken, reinstall:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"
helper install-homebrew
Flatpak-Specific Issues
Desktop application fails to launch
Run with verbose output to diagnose
# Run with verbose output
flatpak run --verbose org.app.Name
# Check logs
journalctl --user -xe | grep flatpak
# Reinstall the application
flatpak uninstall org.app.Name
flatpak install flathub org.app.Name
Application can't access files or directories
Grant filesystem access
# Grant home directory access
flatpak override --user --filesystem=home org.app.Name
# Or for specific directory
flatpak override --user --filesystem=/path/to/dir org.app.Name
Or use Flatseal (pre-installed) for GUI management:
- Open Flatseal from your application menu
- Select the application
- Adjust filesystem permissions as needed
Flatpak apps don't match system theme
Install Flatpak themes
# Install GTK themes
flatpak install flathub org.gtk.Gtk3theme.Breeze
# For Qt apps
flatpak install flathub org.kde.PlatformTheme.QGnomePlatform
Gaming Issues
Steam fails to start or crashes on launch
Clear Steam cache and reinstall
# Clear Steam cache
rm -rf ~/.var/app/com.valvesoftware.Steam/.local/share/Steam
# Reinstall Steam
flatpak uninstall com.valvesoftware.Steam
flatpak install flathub com.valvesoftware.Steam
Games run slowly or stutter
Check drivers and enable optimizations
# Check GPU drivers
lspci -k | grep -EA3 'VGA|3D|Display'
# For AMD GPUs, enable overclocking
helper enable-amdgpu-oc
Make sure GameMode is installed (it's pre-installed on SoltrOS). It automatically optimizes performance when launching games.
Gaming controller not recognized
Check device and restart udev
# Check if controller is detected
lsusb
# Restart udev
sudo udevadm control --reload-rules
sudo udevadm trigger
# Verify controller appears
ls /dev/input/js*
Windows game won't launch via Proton
Try different Proton versions
- In Steam, right-click the game → Properties → Compatibility
- Try different Proton versions
- Install ProtonPlus for Proton-GE (pre-installed)
- Check ProtonDB for game-specific fixes
- Verify game files in Steam
Network Issues
Can't connect to the internet
Check connection and restart NetworkManager
# Check connection status
nmcli device status
# Restart NetworkManager
sudo systemctl restart NetworkManager
# Test connectivity
ping -c 4 8.8.8.8
ping -c 4 google.com
If DNS is the issue, set DNS manually:
sudo nmcli con mod "System eth0" ipv4.dns "8.8.8.8 8.8.4.4"
sudo nmcli con up "System eth0"
WiFi adapter not detected or won't connect
Restart WiFi and check firmware
# Check WiFi device
nmcli device wifi list
# Restart WiFi
nmcli radio wifi off
nmcli radio wifi on
# Check firmware
dmesg | grep firmware
If firmware is missing, it should already be installed. Check logs for specific errors.
Network is slow or unstable
Check for packet loss and try disabling IPv6
# Check for packet loss
ping -c 100 8.8.8.8
# Disable IPv6 if causing issues
sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1
# Make permanent
echo "net.ipv6.conf.all.disable_ipv6 = 1" | sudo tee /etc/sysctl.d/99-disable-ipv6.conf
Display Issues
Display resolution is incorrect
Set resolution via system settings or xrandr
Via GUI:
- KDE: System Settings → Display Configuration
- GNOME: Settings → Displays
Via command line:
# List available resolutions
xrandr
# Set resolution
xrandr --output HDMI-1 --mode 1920x1080
Multiple monitors not working correctly
Configure displays via system settings or xrandr
# List displays
xrandr
# Position monitors
xrandr --output HDMI-1 --right-of eDP-1
Use the GUI display settings for easier configuration.
Visible tearing during video playback or gaming
Check compositor settings
- AMD: Usually works out of the box, check compositor settings in your DE
- Intel: Enable TearFree in compositor settings
- NVIDIA: Nouveau drivers may have tearing, consider adding proprietary drivers
Audio Issues
Audio not working
Check audio system and restart PipeWire
# Check if sound card detected
lspci | grep -i audio
# Check PipeWire status
systemctl --user status pipewire pipewire-pulse
# Restart audio
systemctl --user restart pipewire pipewire-pulse
# Check volume levels
alsamixer
Audio playing through wrong device
Select correct output device
Via GUI:
- KDE: System Settings → Audio → Playback Devices
- GNOME: Settings → Sound
Via command line:
# List audio sinks
pactl list sinks short
# Set default sink
pactl set-default-sink <sink-name>
Container Issues
distrobox enter fails
Check container status and recreate if needed
# Check Podman status
podman ps -a
# View container logs
podman logs distrobox-<container-name>
# Recreate container
distrobox rm <container-name>
distrobox create --name <container-name> --image <image>
Permission denied when running Podman commands
Ensure user namespaces are configured
# Check subuid/subgid
cat /etc/subuid
cat /etc/subgid
# If empty, add entries
echo "$USER:100000:65536" | sudo tee -a /etc/subuid
echo "$USER:100000:65536" | sudo tee -a /etc/subgid
Log out and back in after making these changes.
Performance Issues
System running slow, high CPU usage
Identify resource-heavy processes
# Check CPU usage
btop
# Check systemd services
systemctl list-units --type=service --state=running
# Find CPU-intensive processes
ps aux --sort=-%cpu | head -10
System using too much RAM
Check memory usage and clear cache
# Check memory usage
free -h
# Find memory-intensive processes
ps aux --sort=-%mem | head -10
# Clear cache (safe)
sudo sync
echo 3 | sudo tee /proc/sys/vm/drop_caches
Viewing System Logs
Useful Log Commands
# View recent system logs
journalctl -xe
# View kernel logs
dmesg | tail -50
# View boot logs
journalctl -b
# View specific service logs
journalctl -u <service-name>
# Follow logs in real-time
journalctl -f
Checking System Status
# Check bootc status
sudo bootc status
# Check failed services
systemctl --failed
# Check disk usage
df -h
# Check memory
free -h
Reporting Bugs
Collecting Information for Bug Reports
When reporting issues, collect this information:
# System information
cat /etc/os-release
uname -a
sudo bootc status
# Hardware information
lscpu
lspci
lsusb
# Save logs
journalctl -b > system-logs.txt
dmesg > kernel-logs.txt
Where to Get Help
- Search GitHub Issues: Check existing issues for similar problems
- Report a Bug: Create a new issue with:
- Clear description of the problem
- Steps to reproduce
- System information (bootc status)
- Relevant logs
- What you've already tried
- Check the Wiki: Visit the SoltrOS Wiki for additional documentation
💡 Can't Find a Solution?
If your issue isn't covered here, the Getting Started guide has additional information about common tasks. For persistent problems, open an issue on GitHub with detailed information about your problem.