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