nix-config/docs/troubleshooting.md

Troubleshooting Guide

This guide provides solutions for common issues that may arise when using this NixOS configuration.

System Issues

Failed System Build

Problem: nixos-rebuild switch fails with an error.

Solutions:

1. Syntax Errors:

   • Check the error message for file and line number information
   • Verify the syntax in the mentioned file
   • Common issues include missing semicolons, curly braces, or mismatched quotes

2. Missing Dependencies:

   • If the error mentions a missing package or dependency:

     git pull  # Update to the latest version
     nix flake update  # Update the flake inputs
     

3. Conflicting Modules:

   • Look for modules that might be configuring the same options incompatibly
   • Disable one of the conflicting modules or adjust their configurations

4. Disk Space Issues:

   • Check available disk space with df -h
   • Clear old generations: sudo nix-collect-garbage -d

Boot Issues

Problem: System fails to boot after a configuration change.

Solutions:

1. Boot into a Previous Generation:

   • At the boot menu, select an older generation
   • Once booted, revert the problematic change:

     cd /etc/nixos
     git revert HEAD  # Or edit the files directly
     sudo nixos-rebuild switch
     

2. Boot from Installation Media:

   • Boot from a NixOS installation media
   • Mount your system:

     sudo mount /dev/disk/by-label/nixos /mnt
     sudo mount /dev/disk/by-label/boot /mnt/boot  # If separate boot partition
     

   • Chroot into your system:

     sudo nixos-enter --root /mnt
     cd /etc/nixos
     git revert HEAD  # Or edit the files directly
     nixos-rebuild switch --install-bootloader
     

Home Assistant Issues

Home Assistant Fails to Start

Problem: Home Assistant service fails to start.

Solutions:

1. Check Service Status:

   systemctl status home-assistant
   journalctl -u home-assistant -n 100
   

2. Database Issues:

   • Check PostgreSQL is running: systemctl status postgresql
   • Verify database connection settings in Home Assistant configuration

3. Permission Issues:

   • Check ownership and permissions on config directory:

     ls -la /var/lib/homeassistant
     sudo chown -R hass:hass /var/lib/homeassistant
     sudo chmod -R 750 /var/lib/homeassistant
     

4. Custom Component Issues:

   • Try disabling custom components to isolate the issue:
     • Edit modules/nixos/homeassistant/services/homeassistant/default.nix
     • Comment out the customComponents section
     • Rebuild: sudo nixos-rebuild switch

Zigbee Device Connection Issues

Problem: Zigbee devices fail to connect or are unstable.

Solutions:

1. Verify Device Path:

   • Check the Zigbee coordinator is properly detected:

     ls -la /dev/ttyUSB*
     

   • Update the device path if needed:
     • Edit your system configuration
     • Set mjallen.services.home-assistant.zigbeeDevicePath to the correct path
     • Rebuild: sudo nixos-rebuild switch

2. Interference Issues:

   • Move the Zigbee coordinator away from other wireless devices
   • Try a USB extension cable to improve positioning
   • Change Zigbee channel in Zigbee2MQTT configuration

3. Reset Zigbee2MQTT:

   systemctl restart zigbee2mqtt
   

Automation Issues

Problem: Automations don't run as expected.

Solutions:

1. Check Automation Status:

   • In Home Assistant UI, verify the automation is enabled
   • Check Home Assistant logs for automation execution errors

2. Entity Issues:

   • Verify entity IDs are correct
   • Check if entities are available/connected
   • Test direct service calls to verify entity control works

3. Trigger Issues:

   • Test the automation manually via Developer Tools > Services
   • Use automation.trigger service with the automation's entity_id

Flake Issues

Flake Input Update Errors

Problem: nix flake update fails or causes issues.

Solutions:

1. Selective Updates:

   • Update specific inputs instead of all at once:

     nix flake lock --update-input nixpkgs
     

2. Rollback Flake Lock:

   • If an update causes issues, revert to previous flake.lock:

     git checkout HEAD^ -- flake.lock
     

3. Pin to Specific Revisions:

   • In flake.nix, pin problematic inputs to specific revisions:

     nixpkgs-stable.url = "github:NixOS/nixpkgs/5233fd2ba76a3accb05f88b08917450363be8899";
     

Secret Management Issues

Sops Decryption Errors

Problem: Sops fails to decrypt secrets.

Solutions:

1. Key Issues:

   • Verify your GPG key is available and unlocked
   • Check .sops.yaml includes your key fingerprint

2. Permission Issues:

   • Check file permissions on secret files
   • Make sure the user running nixos-rebuild has access to the GPG key

Network Issues

Firewall Blocks Services

Problem: Services are not accessible due to firewall rules.

Solutions:

1. Check Firewall Status:

   sudo nix-shell -p iptables --run "iptables -L"
   

2. Verify Firewall Configuration:

   • Check if ports are properly allowed in the configuration
   • Add missing ports if necessary

3. Temporary Disable Firewall (for testing only):

   sudo systemctl stop firewall
   # After testing
   sudo systemctl start firewall
   

Getting Help

If you encounter an issue not covered in this guide:

1. Check the NixOS Wiki: https://nixos.wiki/
2. Search the NixOS Discourse forum: https://discourse.nixos.org/
3. Join the NixOS Matrix/Discord community for real-time help
4. File an issue in the repository if you believe you've found a bug