54 lines
2.0 KiB
Markdown
54 lines
2.0 KiB
Markdown
# Hyprland Troubleshooting Matrix
|
|
|
|
## Symptom 1: Black Screen on Boot (NVIDIA)
|
|
- **Cause**: Missing Wayland environment variables or modeset issue.
|
|
- **Investigation**: Check the installed NVIDIA driver documentation and whether `nvidia_drm.modeset=1` is active. If the symptom is specifically cursor-related, test `cursor { no_hardware_cursors = true }` in `hyprland.conf`.
|
|
|
|
## Symptom 2: Screen Sharing Not Working (OBS / Browser)
|
|
- **Cause**: Inactive portal or pipewire environment variable missing.
|
|
- **Fix**: Run:
|
|
```bash
|
|
systemctl --user restart xdg-desktop-portal-hyprland
|
|
systemctl --user restart xdg-desktop-portal
|
|
```
|
|
|
|
## Symptom 3: No Sound Output
|
|
- **Cause**: PipeWire or WirePlumber service failed.
|
|
- **Fix**: Run:
|
|
```bash
|
|
systemctl --user restart pipewire wireplumber
|
|
```
|
|
|
|
## Symptom 4: Cursor Missing or Invisible (NVIDIA)
|
|
- **Cause**: Hardware cursor rendering not supported by GPU driver.
|
|
- **Fix**: Add to `hyprland.conf`:
|
|
```text
|
|
cursor {
|
|
no_hardware_cursors = true
|
|
}
|
|
```
|
|
|
|
## Symptom 5: Apps Blurry or Wrong Scale (XWayland)
|
|
- **Cause**: XWayland apps not using native Wayland rendering.
|
|
- **Fix**: Set environment variables in `hyprland.conf`:
|
|
```text
|
|
env = GDK_BACKEND,wayland,x11
|
|
env = QT_QPA_PLATFORM,wayland;xcb
|
|
env = MOZ_ENABLE_WAYLAND,1
|
|
```
|
|
|
|
## Symptom 6: Multi-Monitor Not Working
|
|
- **Cause**: Incorrect or missing monitor config.
|
|
- **Fix**: Check connected monitors with `hyprctl monitors` and configure in `hyprland.conf`:
|
|
```text
|
|
monitor=,preferred,auto,1
|
|
```
|
|
|
|
## Symptom 7: Flickering / Tearing (NVIDIA)
|
|
- **Cause**: Missing DRM kernel module setting.
|
|
- **Investigation**: Confirm the installed driver's recommended DRM settings before changing boot configuration. If its documentation requires these options, review and add them to `/etc/modprobe.d/nvidia.conf`:
|
|
```text
|
|
options nvidia_drm modeset=1 fbdev=1
|
|
```
|
|
Regenerating initramfs with `sudo dracut --force` is a privileged, boot-critical change. Back up the current configuration and obtain explicit approval before running it.
|