---
title: Troubleshooting Configuration Issues
impact: MEDIUM
impactDescription: Systematic debugging approach for configuration issues
tags: debugging,errors,troubleshooting,verification
---


## Why This Matters

Knowing how to systematically debug NixOS configurations saves hours of frustration and prevents making random changes hoping something works.

## General Approach

Follow this order when debugging:

1. **Read error messages completely** - They usually tell you exactly what's wrong
2. **Verify syntax** - Check for missing brackets, quotes, commas
3. **Validate config** - Use `nixos-rebuild test` first
4. **Check scope** - Is overlay/module in correct location?
5. **Trace dependencies** - Are required inputs/imports present?

## Common Error Patterns

### "undefined variable 'inputs'"

**Cause:** `inputs` not passed via `specialArgs`.

**Fix:**
```nix
# flake.nix
outputs = { self, nixpkgs, ... }@inputs:
{
  nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
    specialArgs = { inherit inputs; };  # Add this
    modules = [ ./hosts/myhost ];
  };
};
```

### "attribute 'package-name' not found"

**Cause:** Package doesn't exist, or overlay not applied.

**Debug:**
```bash
# Check if package exists in nixpkgs
nix search nixpkgs package-name

# Check if overlay is defined
nix eval .#nixosConfigurations.myhost.config.nixpkgs.overlays

# Verify package in your config's pkgs
nix repl
nix-repl> :l flake.nix
nix-repl> myhost.config.environment.systemPackages
```

**Fix:**
- If overlay issue: Move to correct location (see [overlay-scope.md](overlay-scope.md))
- If missing package: Use correct package name or add overlay

### "error: The option 'some.option' does not exist"

**Cause:** Typo in option name, or option not available in your nixpkgs version.

**Debug:**
```bash
# Search for option
nixos-options | grep some-option

# Check option in current config
nix eval .#nixosConfigurations.myhost.config.some.option
```

**Fix:**
- Check option name spelling
- Verify nixpkgs version has this option
- Read option documentation for correct usage

### "infinite recursion"

**Cause:** Circular dependency in config.

**Debug:**
```bash
# Use --show-trace to see where
nixos-rebuild build --flake .#hostname --show-trace
```

**Fix:**
- Look for mutual dependencies
- Use `mkBefore`/`mkAfter` for ordering
- Break circular reference

### "hash mismatch" in flake.lock

**Cause:** Local changes or outdated lock file.

**Fix:**
```bash
# Update flake lock
nix flake update

# Or update specific input
nix flake lock update-input nixpkgs
```

## Overlay Not Applied

**Symptom:** Package from overlay not found.

**Debug steps:**

1. Check overlay definition:
```bash
nix eval .#nixosConfigurations.myhost.config.nixpkgs.overlays
```

2. Check overlay location:
```bash
# If useGlobalPkgs = true, overlay should be here:
grep -r "nixpkgs.overlays" hosts/myhost/default.nix

# NOT here:
grep -r "nixpkgs.overlays" home-manager/home.nix
```

3. Verify overlay input:
```bash
nix flake metadata
# Look for your overlay input
```

**Fix:** See [overlay-scope.md](overlay-scope.md)

## Configuration Changes Not Applying

**Symptom:** Edit config, rebuild, but nothing changes.

**Debug steps:**

1. Verify rebuild ran successfully:
```bash
sudo nixos-rebuild switch --flake .#hostname
# Look for "success" message
```

2. Check current generation:
```bash
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system
```

3. Verify new generation is active:
```bash
sudo nixos-version
# Should show timestamp of recent rebuild
```

4. Check if option actually changed:
```bash
nix eval .#nixosConfigurations.myhost.config.some.option
```

**Fix:**
- Ensure rebuild succeeded
- Check if service needs restart: `systemctl restart service-name`
- For Home Manager: `home-manager switch` (or `sudo nixos-rebuild switch` if integrated)

## Build Fails with "store collision"

**Symptom:** Multiple packages trying to write to same path.

**Cause:** Usually duplicate package declarations or conflicting modules.

**Fix:**
- Remove duplicate package declarations
- Check for conflicting modules
- Use `--show-trace` to identify conflicting packages

## Verification Commands

### Check configuration without building

```bash
# Check syntax
nix flake check

# Dry run build
nixos-rebuild build --flake .#hostname --dry-run

# Evaluate specific option
nix eval .#nixosConfigurations.myhost.config.environment.systemPackages
```

### Test configuration safely

```bash
# Build without activating
nixos-rebuild build --flake .#hostname

# Test configuration (rollback on reboot)
nixos-rebuild test --flake .#hostname

# Switch (persistent)
nixos-rebuild switch --flake .#hostname
```

### Compare generations

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

# List Home Manager generations
home-manager generations

# Compare configurations
sudo nix diff-closures /nix/var/nix/profiles/system-*-link
```

## Useful Tools

### nix repl

```bash
nix repl
nix-repl> :l flake.nix                    # Load flake
nix-repl> myhost.config.environment.systemPackages  # Access config
nix-repl> :b myhost.config.system.build.toplevel   # Build
```

### nixos-version

```bash
# Check current system version
nixos-version

# Should show something like:
# 25.05.20250123.abc1234
```

### journalctl

```bash
# Check service logs for failures
sudo journalctl -xe

# Check NixOS rebuild logs
sudo journalctl -u nixos-rebuild
```

## Getting Help

When asking for help, provide:

1. **Full error message** (not just "it doesn't work")
2. **Minimal reproducible example**
3. **NixOS version**: `nixos-version`
4. **Relevant config files**
5. **What you've tried**
6. **Expected vs actual behavior**

Useful commands:
```bash
# Show system info
nixos-version
uname -a

# Show flake info
nix flake metadata

# Export config for sharing
nixos-rebuild build --flake .#hostname
nix-store -qR result > system-closure
```

## Common Debugging Workflows

### Package not found

```bash
# 1. Search for package
nix search nixpkgs package-name

# 2. Check if it's available for your system
nix eval nixpkgs#legacyPackages.x86_64-linux.package-name

# 3. Check your overlays
nix eval .#nixosConfigurations.myhost.config.nixpkgs.overlays

# 4. Check if overlay provides it
nix eval .#packages.x86_64-linux.package-name
```

### Overlay not applying

```bash
# 1. Verify overlay is defined
grep -r "overlays" hosts/myhost/

# 2. Check useGlobalPkgs setting
grep "useGlobalPkgs" hosts/myhost/default.nix

# 3. Evaluate overlay
nix eval .#nixosConfigurations.myhost.config.nixpkgs.overlays

# 4. Test package directly
nix build .#packages.x86_64-linux.package-name
```

### Service not starting

```bash
# 1. Check service status
systemctl status service-name

# 2. View service logs
journalctl -xeu service-name

# 3. Check service config
nixos-rebuild build --flake .#hostname --show-trace

# 4. Test service manually
/path/to/service-binary --verbose
```