gentoo-legion/docs/troubleshooting.md

Troubleshooting Guide

Common issues and solutions for Gentoo + Hyprland on Legion laptops.

Display Issues

Pink/Artifacts on External Monitors

1. Check BIOS setting - Must be set to Hybrid/Dynamic (not Discrete)

2. Let Hyprland auto-detect GPUs - Comment out AQ_* variables in ENVariables.conf:

   # env = AQ_DRM_DEVICES,...
   # env = AQ_MGPU_NO_EXPLICIT,...
   

3. Try explicit GPU order as fallback:

   env = AQ_DRM_DEVICES,/dev/dri/card1:/dev/dri/card0
   env = AQ_MGPU_NO_EXPLICIT,1
   

Duplicate Mouse Cursors (Multi-GPU)

In ~/.config/hypr/configs/SystemSettings.conf:

cursor {
    no_hardware_cursors = 2
}

External Monitors Not Detected

1. Check physical connections
2. Verify NVIDIA driver: lsmod | grep nvidia
3. Check monitor names: hyprctl monitors
4. Verify DRM is enabled: cat /sys/module/nvidia_drm/parameters/modeset

Screen Tearing

Ensure NVIDIA DRM modeset is enabled in:

• /etc/modprobe.d/nvidia.conf: options nvidia_drm modeset=1
• GRUB: GRUB_CMDLINE_LINUX_DEFAULT="nvidia_drm.modeset=1 ..."

Boot Issues

Swap Not Activating

Gentoo uses /etc/conf.d/dmcrypt, not /etc/crypttab for encrypted swap.

1. Check dmcrypt config:

   cat /etc/conf.d/dmcrypt
   

2. Ensure dmcrypt is in boot runlevel:

   rc-update add dmcrypt boot
   

3. Verify swap partition path is correct

LUKS Prompt Not Appearing

1. Verify dracut includes crypt module:

   lsinitrd /boot/initramfs-*.img | grep crypt
   

2. Check /etc/dracut.conf.d/crypt.conf exists

3. Rebuild initramfs:

   emerge --config sys-kernel/gentoo-kernel
   

"failed to start user.greetd" Error

Use custom PAM config for greetd that omits pam_openrc.so. See greetd Setup.

Shell Issues

Zsh Plugins Not Loading

Gentoo paths differ from other distros:

# Correct Gentoo paths
/usr/share/zsh/site-functions/zsh-autosuggestions.zsh
/usr/share/zsh/site-functions/zsh-syntax-highlighting.zsh

# NOT
/usr/share/zsh/plugins/...

Starship Colors Overridden by Wallust

Use hex codes instead of color names in starship.toml:

# Good
format = "[](#89b4fa)..."

# Bad (wallust overrides)
format = "[](blue)..."

Service Issues

Service Won't Start

1. Check for error messages:

   rc-service <service> status
   

2. Check dependencies:

   rc-service <service> start --verbose
   

3. Review logs:

   cat /var/log/messages | grep <service>
   

OpenRC vs systemd Commands

Task	OpenRC	systemd
Start service	rc-service <name> start	systemctl start <name>
Stop service	rc-service <name> stop	systemctl stop <name>
Enable at boot	rc-update add <name> default	systemctl enable <name>
Check status	rc-service <name> status	systemctl status <name>
Reboot	loginctl reboot	systemctl reboot
Poweroff	loginctl poweroff	systemctl poweroff
Suspend	loginctl suspend	systemctl suspend

Network Issues

NetworkManager Not Working

1. Ensure it's in default runlevel:

   rc-update add NetworkManager default
   

2. Check status:

   rc-service NetworkManager status
   

3. Use nmcli for configuration:

   nmcli device wifi list
   nmcli device wifi connect "SSID" password "password"
   

DNS Resolution Failing

Check /etc/resolv.conf:

cat /etc/resolv.conf

If empty or wrong, NetworkManager may need configuration:

# /etc/NetworkManager/conf.d/dns.conf
[main]
dns=default

Performance Issues

System Running Hot

1. Check power profile:

   powerprofilesctl get
   powerprofilesctl set balanced  # or power-saver
   

Slow Compilation

1. Verify ccache is working:

   ccache -s
   

2. Check make.conf MAKEOPTS:

   # Should match CPU threads
   MAKEOPTS="-j16"
   

Portage Issues

WebKit-GTK Out of Memory

net-libs/webkit-gtk is extremely memory-hungry during compilation. If your build gets OOM-killed:

1. Resume the emerge, skipping the failed package:

   emerge --resume --skipfirst
   

2. Create a package-specific environment to limit parallelism:

   mkdir -p /etc/portage/env /etc/portage/package.env
   echo 'MAKEOPTS="-j4"' > /etc/portage/env/webkit-gtk.conf
   echo 'NINJAOPTS="-j4"' >> /etc/portage/env/webkit-gtk.conf
   echo 'net-libs/webkit-gtk webkit-gtk.conf' >> /etc/portage/package.env/webkit-gtk
   

3. Build webkit-gtk with reduced parallelism:

   emerge net-libs/webkit-gtk
   

Adjust -j4 based on your available RAM (roughly 2-3GB per job). With 24GB RAM, -j6 to -j8 is usually safe.

LLVM/Clang GCC 15 ICE (Steam 32-bit)

When building LLVM with abi_x86_32 for Steam, GCC 15 may crash with an internal compiler error (ICE):

internal compiler error: Segmentation fault

This typically occurs in AMDGPURewriteAGPRCopyMFMA.cpp and is triggered by -march=znver3 optimizations.

Fix: Have LLVM compile itself with clang instead of GCC:

# Add to /etc/portage/package.use/steam
llvm-core/llvm clang
llvm-core/clang clang

This is already included in the provided package.use/steam file.

Circular Dependency (freetype/harfbuzz)

During initial install, use -harfbuzz flag temporarily:

# /etc/portage/package.use/circular-dependencies
media-libs/freetype -harfbuzz

After @world compiles, remove and rebuild:

# Remove the line, then:
emerge -1 media-libs/freetype media-libs/harfbuzz

Package Masked

For ~amd64 packages, add to accept_keywords:

# /etc/portage/package.accept_keywords/<category>
<package> ~amd64

USE Flag Conflicts

Check required USE flags:

emerge -pv <package>

Add missing flags to /etc/portage/package.use/.

Getting Help

1. Check Gentoo Wiki: https://wiki.gentoo.org/
2. Check Hyprland Wiki: https://wiki.hyprland.org/
3. Review system logs: /var/log/messages
4. Check application-specific logs in ~/.local/log/ or /var/log/