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:
   ```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.

### 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/`