277 lines
6.1 KiB
Markdown
277 lines
6.1 KiB
Markdown
# 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:
|
|
```bash
|
|
# env = AQ_DRM_DEVICES,...
|
|
# env = AQ_MGPU_NO_EXPLICIT,...
|
|
```
|
|
|
|
3. **Try explicit GPU order** as fallback:
|
|
```bash
|
|
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:
|
|
```bash
|
|
cat /etc/conf.d/dmcrypt
|
|
```
|
|
|
|
2. Ensure dmcrypt is in boot runlevel:
|
|
```bash
|
|
rc-update add dmcrypt boot
|
|
```
|
|
|
|
3. Verify swap partition path is correct
|
|
|
|
### LUKS Prompt Not Appearing
|
|
|
|
1. Verify dracut includes crypt module:
|
|
```bash
|
|
lsinitrd /boot/initramfs-*.img | grep crypt
|
|
```
|
|
|
|
2. Check `/etc/dracut.conf.d/crypt.conf` exists
|
|
|
|
3. Rebuild initramfs:
|
|
```bash
|
|
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](greetd-setup.md).
|
|
|
|
## Shell Issues
|
|
|
|
### Zsh Plugins Not Loading
|
|
|
|
Gentoo paths differ from other distros:
|
|
```bash
|
|
# 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`:
|
|
```toml
|
|
# Good
|
|
format = "[](#89b4fa)..."
|
|
|
|
# Bad (wallust overrides)
|
|
format = "[](blue)..."
|
|
```
|
|
|
|
## Service Issues
|
|
|
|
### Service Won't Start
|
|
|
|
1. Check for error messages:
|
|
```bash
|
|
rc-service <service> status
|
|
```
|
|
|
|
2. Check dependencies:
|
|
```bash
|
|
rc-service <service> start --verbose
|
|
```
|
|
|
|
3. Review logs:
|
|
```bash
|
|
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:
|
|
```bash
|
|
rc-update add NetworkManager default
|
|
```
|
|
|
|
2. Check status:
|
|
```bash
|
|
rc-service NetworkManager status
|
|
```
|
|
|
|
3. Use nmcli for configuration:
|
|
```bash
|
|
nmcli device wifi list
|
|
nmcli device wifi connect "SSID" password "password"
|
|
```
|
|
|
|
### DNS Resolution Failing
|
|
|
|
Check `/etc/resolv.conf`:
|
|
```bash
|
|
cat /etc/resolv.conf
|
|
```
|
|
|
|
If empty or wrong, NetworkManager may need configuration:
|
|
```bash
|
|
# /etc/NetworkManager/conf.d/dns.conf
|
|
[main]
|
|
dns=default
|
|
```
|
|
|
|
## Performance Issues
|
|
|
|
### System Running Hot
|
|
|
|
1. Check power profile:
|
|
```bash
|
|
powerprofilesctl get
|
|
powerprofilesctl set balanced # or power-saver
|
|
```
|
|
|
|
### Slow Compilation
|
|
|
|
1. Verify ccache is working:
|
|
```bash
|
|
ccache -s
|
|
```
|
|
|
|
2. Check make.conf MAKEOPTS:
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
emerge --resume --skipfirst
|
|
```
|
|
|
|
2. Create a package-specific environment to limit parallelism:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
# /etc/portage/package.use/circular-dependencies
|
|
media-libs/freetype -harfbuzz
|
|
```
|
|
|
|
After @world compiles, remove and rebuild:
|
|
```bash
|
|
# Remove the line, then:
|
|
emerge -1 media-libs/freetype media-libs/harfbuzz
|
|
```
|
|
|
|
### Package Masked
|
|
|
|
For ~amd64 packages, add to accept_keywords:
|
|
```bash
|
|
# /etc/portage/package.accept_keywords/<category>
|
|
<package> ~amd64
|
|
```
|
|
|
|
### USE Flag Conflicts
|
|
|
|
Check required USE flags:
|
|
```bash
|
|
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/`
|