playbook/antigravity-awesome-skills/skills/fedora-hyprland-installer/references/troubleshooting.md

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:

  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:

  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:

  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:

  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:

  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:

  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.