Troubleshooting

This guide covers common issues you might encounter when using or adapting this configuration, along with their solutions.

Build errors

Error: attribute 'something' missing

Symptom:

error: attribute 'xyz' missing

Common causes:

Referencing a user that doesn’t exist in garden.system.users
Missing module import
Typo in attribute path

Solution:

Verify the attribute exists in your configuration
Check that all required modules are imported
Ensure users are declared in modules/base/users/options.nix

Error: infinite recursion

Symptom:

error: infinite recursion encountered

Common causes:

Circular module imports
Self-referencing option definitions

Solution:

Check for circular imports in your module structure
Use mkDefault, mkForce, or mkOverride to break recursion
Review option definitions for self-references

# Bad - causes recursion
services.foo.enable = config.services.foo.enable;

# Good - uses mkDefault
services.foo.enable = lib.mkDefault true;

Error: collision between packages

Symptom:

error: collision between `package-a` and `package-b`

Cause: Two packages provide the same binary or file.Solution: Use lib.lowPrio or remove one package:

garden.packages = {
  inherit (pkgs) package-a;
  package-b-low = lib.lowPrio pkgs.package-b;
};

Hash mismatch errors

Symptom:

error: hash mismatch in fixed-output derivation

Cause: Flake lock is outdated or corrupted.Solution:

# Update flake inputs
nix flake update

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

# Rebuild
sudo nixos-rebuild switch --flake .#yoursystem

System configuration issues

System doesn't boot after rebuild

Solution:

Boot from a previous generation in GRUB
Check the system log:
```
journalctl -xb
```
Review recent changes:
```
git diff HEAD~1
```

Rebuild with the working configuration:

sudo nixos-rebuild switch --flake .#yoursystem --rollback

No users can log in

Symptom: Cannot log in as any user after rebuild.Cause: Users not properly configured or password issues.Solution:

Boot into recovery mode or single-user mode
Verify user configuration:
```
garden.system.users = [ "yourname" ];
```
Reset password:
```
# As root
passwd yourname
```
Check that user files exist:
- /modules/base/users/yourname.nix
- /modules/nixos/users/yourname.nix

Network not working after boot

Solution: Check NetworkManager status:

systemctl status NetworkManager

Enable if disabled:

networking.networkmanager.enable = true;

For servers, configure static networking:

networking = {
  interfaces.eth0.ipv4.addresses = [{
    address = "192.168.1.100";
    prefixLength = 24;
  }];
  defaultGateway = "192.168.1.1";
  nameservers = [ "8.8.8.8" "1.1.1.1" ];
};

Secrets management issues

Error: no key could decrypt the data

Symptom:

Failed to get the data key required to decrypt the SOPS file.

Solution:

Verify your age key exists:
```
ls ~/.config/sops/age/keys.txt
```

Check your key is in .sops.yaml:

ssh-to-age < ~/.ssh/id_ed25519.pub
# Compare with .sops.yaml

Update secret keys:
```
sops updatekeys secrets/yourfile.yaml
```

Secrets not available at runtime

Symptom: Service fails because secret file doesn’t exist.Solution:

Verify secret is defined:

sops.secrets.my-secret = {
  sopsFile = ./secrets/file.yaml;
};

Check secret path:

# Secrets are in /run/secrets/ by default
ls -l /run/secrets/

Verify permissions:

sops.secrets.my-secret = {
  owner = "myuser";
  mode = "0400";
};

Cannot edit secrets

Symptom: sops secrets/file.yaml fails.Solution:

Ensure sops is installed:
```
nix-shell -p sops
```

Set EDITOR environment variable:

export EDITOR=nvim
sops secrets/file.yaml

Check age key exists:
```
ls ~/.config/sops/age/keys.txt
```

Home-manager issues

Home-manager activation fails

Symptom:

error: collision between ... and ...

Cause: Conflicting home-manager configurations.Solution:

Check for duplicate package definitions

Use lib.mkForce to override:

programs.git.enable = lib.mkForce true;

Remove conflicting manual installations

XDG directories not created

Solution: Ensure XDG is properly configured:

xdg = {
  enable = true;
  userDirs = {
    enable = true;
    createDirectories = true;
  };
};

macOS-specific issues

chmod error on /nix/store

Symptom:

error: chmod '/nix/store/...': Operation not permitted

Cause: Nix doesn’t have Full Disk Access on macOS.Solution:

Open System Settings → Privacy & Security → Full Disk Access
Click the + button
Add /nix (or the nix daemon)
Run garbage collection again:
```
nix store gc
```

Performance issues

Builds are very slow

Solutions:

Enable binary cache:

nix.settings = {
  substituters = [
    "https://cache.nixos.org"
    "https://nix-community.cachix.org"
  ];
  trusted-public-keys = [
    "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
    "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="
  ];
};

Use more cores:

nix.settings = {
  cores = 8;
  max-jobs = 4;
};

Enable parallel building:

nixos-rebuild switch --flake .#yoursystem --cores 0

Evaluation is slow

Solution:

Reduce imported modules
Use lib.mkDefault instead of heavy conditionals
Avoid deep recursion in option definitions

Profile with:

nix eval --show-trace .#nixosConfigurations.yoursystem.config.system.build.toplevel

Debugging techniques

Enable trace messages

nixos-rebuild switch --flake .#yoursystem --show-trace

Check what’s being built

nixos-rebuild dry-build --flake .#yoursystem

Inspect configuration

# View full configuration
nix eval .#nixosConfigurations.yoursystem.config --json | jq

# Check specific option
nix eval .#nixosConfigurations.yoursystem.config.services.nginx.enable

View build logs

# System logs
journalctl -xe

# Specific service
journalctl -u nginx.service

# Nix build logs
nix log /nix/store/...-system

Test in VM

# Build and run in VM
nixos-rebuild build-vm --flake .#yoursystem
./result/bin/run-*-vm

Getting help

If you’re still stuck:

NixOS Discourse

Community forum for questions and discussions

NixOS Wiki

Community-maintained documentation

GitHub Issues

Report issues specific to this repository

NixOS Manual

Official NixOS documentation

Common debugging commands

# Check flake
nix flake check

# Update inputs
nix flake update

# Show flake info
nix flake show

# Evaluate configuration
nix eval .#nixosConfigurations.yoursystem.config.system.build.toplevel

# Check for evaluation errors
nixos-rebuild dry-build --flake .#yoursystem --show-trace

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

# Garbage collect
sudo nix-collect-garbage -d

# Optimize store
nix-store --optimize

Next steps

Making it your own

Customize the configuration

Adding systems

Set up new systems

Secrets management

Configure encrypted secrets

Architecture overview

Understand the architecture

Get Started

Architecture

Installation

Guides

Configuration

Build errors

System configuration issues

Secrets management issues

Home-manager issues

macOS-specific issues

Performance issues

Debugging techniques

Enable trace messages

Check what’s being built

Inspect configuration

View build logs

Test in VM

Getting help

NixOS Discourse

NixOS Wiki

GitHub Issues

NixOS Manual

Common debugging commands

Next steps

Making it your own

Adding systems

Secrets management

Architecture overview

Build docs developers (and LLMs) love

Get Started

Architecture

Installation

Guides

Configuration

​Build errors

​System configuration issues

​Secrets management issues

​Home-manager issues

​macOS-specific issues

​Performance issues

​Debugging techniques

​Enable trace messages

​Check what’s being built

​Inspect configuration

​View build logs

​Test in VM

​Getting help

NixOS Discourse

NixOS Wiki

GitHub Issues

NixOS Manual

​Common debugging commands

​Next steps

Making it your own

Adding systems

Secrets management

Architecture overview

Build docs developers (and LLMs) love

Build errors

System configuration issues

Secrets management issues

Home-manager issues

macOS-specific issues

Performance issues

Debugging techniques

Enable trace messages

Check what’s being built

Inspect configuration

View build logs

Test in VM

Getting help

Common debugging commands

Next steps