Troubleshooting

Troubleshooting

Common issues and solutions for NullOS.

Build Errors

"error: attribute 'X' missing"

Problem: Missing or misspelled variable in configuration.

Solution:

1. Check spelling in variables.nix
2. Ensure all required variables are set
3. Compare with variables.nix.example

diff variables.nix variables.nix.example

"infinite recursion encountered"

Problem: Circular dependency in configuration.

Solution:

1. Check for self-referencing variables
2. Look for imports that create loops
3. Use nix-instantiate to debug:

nix-instantiate --eval --strict --show-trace

"attribute 'packages' missing"

Problem: Incorrect package reference or syntax error.

Solution:

Check syntax in package lists:

# Wrong
environment.systemPackages = with pkgs; 
  vim
  git
];

# Correct
environment.systemPackages = with pkgs; [
  vim
  git
];

"hash mismatch"

Problem: Package hash doesn't match expected value.

Solution:

1. Update flake:

nix flake update

2. Clear nix store:

nix-collect-garbage -d

3. Rebuild:

sudo nixos-rebuild switch --flake .#hostname

---

Boot Issues

Black Screen After Boot

Possible Causes:

• NVIDIA driver issues
• Display manager not starting
• Incorrect monitor configuration

Solutions:

**1. Boot to console:

• At GRUB, press 'e' on the boot entry
• Find the line starting with linux or linuxefi
• Remove 'quiet' and 'splash' if present
• Add nomodeset to the end of the line
• Boot with Ctrl+X or F10

2. Check logs:

sudo journalctl -xb

3. Disable NVIDIA temporarily:

# In variables.nix
useNvidiaPrime = false;

4. Try previous generation:
   • Select older generation from GRUB menu

GRUB Not Showing

Problem: System boots directly without menu.

Solution:

# In modules/system/boot.nix
boot.loader.timeout = 10;  # Show menu for 10 seconds

Can't Boot Into Older Generation

Problem: Old generations not in menu.

Solution:

# List generations
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system

# Set specific generation
sudo nix-env --switch-generation 42 --profile /nix/var/nix/profiles/system

---

Display Issues

No Display Output

Solutions:

1. Check monitor connection:

hyprctl monitors

2. Manual monitor config:

# In variables.nix
extraMonitorSettings = "
  monitor = eDP-1, 1920x1080@60, 0x0, 1
  ";

3. Reset to auto:

extraMonitorSettings = "";

Multi-Monitor Not Working

Solution:

Use nwg-displays (press F8) or manually:

# List available outputs
hyprctl monitors

# Test configuration
hyprctl keyword monitor "DP-1,2560x1440@144,0x0,1"

Make permanent in variables.nix:

extraMonitorSettings = "
  monitor = DP-1, 2560x1440@144, 0x0, 1
  monitor = HDMI-A-1, 1920x1080@60, 2560x0, 1
  ";

Screen Tearing

Solution:

# In home/hyprland/hyprland.nix
general = {
  allow_tearing = false;
};

For NVIDIA:

env = WLR_DRM_NO_ATOMIC,1

---

Hyprland Issues

Hyprland Won't Start

Check logs:

journalctl --user -u hyprland -f

Common fixes:

1. Missing environment variables:

# In home/hyprland/env.nix
env = [
  "XDG_CURRENT_DESKTOP,Hyprland"
  "XDG_SESSION_TYPE,wayland"
  "XDG_SESSION_DESKTOP,Hyprland"
];

2. NVIDIA cursor issues:

env = [
  "WLR_NO_HARDWARE_CURSORS,1"
];

Keybindings Not Working

Solutions:

1. Check for conflicts:

hyprctl binds

2. Verify syntax:

# Correct
bind = SUPER, Return, exec, ghostty

# Wrong - missing comma
bind = SUPER Return exec ghostty

3. Reload config:

hyprctl reload

Applications Not Launching

Debug:

# Try from terminal
ghostty
firefox

# Check if installed
which ghostty

Fix path:

# Ensure apps are in packages
home.packages = with pkgs; [
  ghostty
  firefox
];

---

Audio Issues

No Sound

Solutions:

1. Check PipeWire:

systemctl --user status pipewire
systemctl --user status pipewire-pulse

2. Restart audio:

systemctl --user restart pipewire pipewire-pulse

3. Check volume:

wpctl status
wpctl set-volume @DEFAULT_AUDIO_SINK@ 50%

4. Select output:
   • Press SUPER + M to open Pavucontrol
   • Check Configuration and Output Devices tabs

Audio Crackling

Solution:

# In modules/system/audio.nix
services.pipewire.extraConfig.pipewire = {
  "context.properties" = {
    "default.clock.rate" = 48000;
    "default.clock.quantum" = 1024;
    "default.clock.min-quantum" = 512;
  };
};

Bluetooth Audio Issues

Solutions:

# Restart Bluetooth
sudo systemctl restart bluetooth

# Check codec
pactl list | grep bluetooth

Enable better codecs:

hardware.bluetooth = {
  enable = true;
  settings = {
    General = {
      Enable = "Source,Sink,Media,Socket";
    };
  };
};

---

Network Issues

WiFi Not Working

Solutions:

1. Check interface:

ip link
nmcli device status

2. Enable NetworkManager:

networking.networkmanager.enable = true;

3. Connect to network:

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

RTL8852CU WiFi Adapter

Solution:

# In variables.nix
add_rtl8852cu = true;

VPN Not Connecting

Tailscale:

# Check status
tailscale status

# Reauthenticate
tailscale up

Mullvad:

mullvad status
mullvad connect

---

Package Issues

Package Build Failed

Solutions:

1. Check build log:

nix log /nix/store/failed-build-path

2. Update flake:

nix flake update

3. Try stable version:

environment.systemPackages = [
  pkgs.stable.package-name
];

Package Not Found

Solutions:

1. Search correctly:

nix search nixpkgs package-name

2. Check if unfree:

# Should already be enabled
nixpkgs.config.allowUnfree = true;

3. Use correct attribute:

# Find exact name
nix search nixpkgs --json "package" | jq

---

Home Manager Issues

"collision between X and Y"

Problem: Two packages provide the same file.

Solution:

Use priority or overlay:

home.packages = [
  (pkgs.package1.overrideAttrs (old: {
    meta = old.meta // { priority = 1; };
  }))
  pkgs.package2
];

Home Manager Config Not Applying

Solutions:

1. Rebuild home-manager:

home-manager switch --flake .

2. Check for errors:

home-manager switch --flake . --show-trace

3. Restart user services:

systemctl --user daemon-reload

---

Performance Issues

Slow Boot

Check boot time:

systemd-analyze
systemd-analyze blame

Solutions:

1. Disable unnecessary services:

services.unnecessary-service.enable = false;

2. Optimize nix:

nix.settings = {
  auto-optimise-store = true;
  max-jobs = "auto";
};

High CPU Usage

Check processes:

btop
htop

Common culprits:

1. Baloo indexer (KDE):

services.baloo.enable = false;

2. Update services:

systemctl list-units --type=service --state=running

High Memory Usage

Check usage:

free -h
btop

Solutions:

1. Increase swap:

swapDevices = [{
  device = "/swapfile";
  size = 16384;  # 16GB
}];

2. Disable memory-hungry services

---

Git Issues

Git Not Configured

Solution:

# In variables.nix
gitUsername = "Your Name";
gitEmail = "you@email.com";

Or manually:

git config --global user.name "Your Name"
git config --global user.email "you@email.com"

SSH Keys for GitHub

Generate key:

nix-shell -p openssh --run "ssh-keygen -t ed25519 -C 'your@email.com'"

Add to GitHub:

cat ~/.ssh/id_ed25519.pub
# Copy output to GitHub Settings → SSH Keys

Test:

ssh -T git@github.com

---

Nix-Specific Issues

"experimental features not enabled"

Solution:

Should already be enabled in NullOS, but verify:

# In flake.nix or configuration.nix
nix.settings.experimental-features = [ "nix-command" "flakes" ];

Disk Space Full

Clean up:

# Remove old generations
sudo nix-collect-garbage -d

# Optimize store
nix-store --optimise

# Check space
df -h /nix/store

Slow Nix Operations

Solutions:

1. Parallelize builds:

nix.settings.max-jobs = "auto";
nix.settings.cores = 4;

2. Use binary cache:

nix.settings.substituters = [
  "https://cache.nixos.org"
  "https://nix-community.cachix.org"
];

---

File System Issues

/tmp Full

Solution:

boot.tmp = {
  useTmpfs = true;
  tmpfsSize = "50%";  # Increase size
};

Permission Denied

Common fixes:

# For user files
chmod +x file.sh

# For system files (be careful!)
sudo chmod +x /path/to/file

For Nix store (DO NOT MODIFY): Nix store is read-only by design. Rebuild instead.

---

Recovery Procedures

System Won't Boot

1. Boot from NixOS live USB
2. Mount partitions:

sudo mount /dev/sdXn /mnt
sudo mount /dev/sdXm /mnt/boot

3. Chroot:

sudo nixos-enter

4. Rollback or rebuild:

# List generations
nix-env --list-generations --profile /nix/var/nix/profiles/system

# Switch to old generation
nix-env --switch-generation 42 --profile /nix/var/nix/profiles/system

Lost Password

From live USB:

sudo mount /dev/sdXn /mnt
sudo nixos-enter
passwd username

Corrupted Nix Store

Verify store:

nix-store --verify --check-contents

Repair:

nix-store --verify --check-contents --repair

---

Getting Help

Check Logs

System logs:

journalctl -xe
journalctl -b  # Current boot
journalctl -u service-name

User services:

journalctl --user -xe

Hyprland logs:

cat ~/.cache/hyprland/hyprland.log

Debug Mode

Verbose rebuild:

sudo nixos-rebuild switch --flake .#hostname --show-trace

Nix debug:

nix develop --debugger

Community Resources

• NixOS Discourse: https://discourse.nixos.org
• NixOS Wiki: https://nixos.wiki
• Hyprland Discord: https://discord.gg/hyprland
• r/NixOS: https://reddit.com/r/nixos
• Matrix: #nixos:matrix.org

Reporting Issues

When asking for help, include:

1. NixOS version:

nixos-version

2. Relevant config snippet

3. Error message:

# Full error output
sudo nixos-rebuild switch --flake .#hostname 2>&1 | tee error.log

4. Logs:

journalctl -xe > journal.log

---

Preventive Measures

Regular Maintenance

# Weekly: Update flake
nix flake update

# Weekly: Garbage collect old generations
sudo nix-collect-garbage -d

# Monthly: Optimize store
nix-store --optimise

# Before big changes: Commit to git
git add .
git commit -m "Working config before changes"

Backup Strategy

1. Git repository - Version control your config
2. Restic backups - Automated backups configured
3. Keep old generations - Don't delete all immediately

Testing Changes

# Build only (don't activate)
sudo nixos-rebuild build --flake .#hostname

# Test (temporary, reverts on reboot)
sudo nixos-rebuild test --flake .#hostname

# Switch (permanent)
sudo nixos-rebuild switch --flake .#hostname

---

Advanced Debugging

Trace Evaluation

nix-instantiate --eval --strict --show-trace '<nixpkgs/nixos>' -A config.system.build.toplevel

Build with Debug

nix build --keep-failed --show-trace

Check Derivation

nix derivation show .#nixosConfigurations.hostname.config.system.build.toplevel

---

Quick Fixes Checklist

When something breaks:

• Check recent changes (git log)
• Review error message carefully
• Check system logs (journalctl)
• Try rebuilding (sudo nixos-rebuild switch)
• Reboot
• Boot into previous generation
• Check NixOS wiki/discourse for similar issues
• Ask in community channels

---

Next Steps

• File Structure - Understanding configuration layout
• Variables Reference - Configuration variables
• Recovery - Advanced recovery procedures
• Customization Guide - Avoiding issues while customizing