Troubleshooting Guide
This document contains solutions to common issues you might encounter with this NixOS/Darwin configuration.
Nix Version Conflicts
Problem: Build uses different nix version than configuration evaluates to
Symptoms:
nix eval .#darwinConfigurations.darwin.pkgs.nix.version
shows one version (e.g., 2.28.4)- Build output shows building an older version (e.g.,
nix-2.28.3.drv
) - Terminal crashes or build failures with version mismatches
Cause: A flake input is using its own pinned nixpkgs instead of following your main nixpkgs input with overlays applied.
Solution:
- Identify which input is causing the issue by checking
flake.lock
- Update the problematic input to follow your main nixpkgs:
# In flake.nix inputs problematic-input = { url = "github:owner/repo"; inputs.nixpkgs.follows = "nixpkgs"; };
- Update the flake:
nix flake update problematic-input
Example:
# Before
nixvim.url = "github:dc-tec/nixvim";
# After
nixvim = {
url = "github:dc-tec/nixvim";
inputs.nixpkgs.follows = "nixpkgs";
};
Build Issues
Problem: "error: cached failure of attribute"
Symptoms:
- Builds fail with cached failure messages
- Previously working builds suddenly stop working
Solutions:
Clear the evaluation cache:
nix store delete /nix/store/*-eval-cache*
Force rebuild without cache:
nix build --rebuild .#darwinConfigurations.darwin.system
Problem: Out of disk space during builds
Symptoms:
- "No space left on device" errors
- Large
/nix/store
directory
Solutions:
Run garbage collection:
nix store gc --extra-experimental-features nix-command
Clean older generations:
# Darwin sudo nix-env --delete-generations old --profile /nix/var/nix/profiles/system # NixOS sudo nix-collect-garbage --delete-older-than 7d
Optimize store:
nix store optimise
Home Manager Issues
Problem: Home Manager activation fails with file conflicts
Symptoms:
- "File exists" errors during
darwin-rebuild switch
- Conflicts with existing dotfiles
Solutions:
Enable backup file extension (already configured):
home-manager.backupFileExtension = "backup";
Manually remove conflicting files:
rm ~/.config/conflicting-file
Use
home-manager switch --backup-extension backup
for manual runs
Problem: Home Manager options not applying
Symptoms:
- Configuration changes don't take effect
- Programs not installed despite being enabled
Solutions:
Check if the user configuration is properly imported:
nix eval .#darwinConfigurations.darwin.config.home-manager.users.${USER}
Manually run home-manager:
home-manager switch --flake .
Check for conflicting system-level and home-manager packages
Darwin-Specific Issues
Problem: "darwin-rebuild: command not found"
Solution:
# Install nix-darwin
nix run nix-darwin -- switch --flake .
# Or add to shell temporarily
nix shell nixpkgs#darwin-rebuild
Problem: Homebrew apps not installing
Symptoms:
- Homebrew packages defined but not installed
brew list
doesn't show expected packages
Solutions:
Run Homebrew commands manually:
/opt/homebrew/bin/brew bundle --file=/opt/homebrew/Brewfile
Check Homebrew configuration in
modules/darwin/homebrew/
Ensure nix-homebrew is properly configured
Problem: System preferences reset after rebuild
Symptoms:
- macOS system settings revert to defaults
- Dock, keyboard settings, etc. reset
Solution:
Review and update modules/darwin/system.nix
to include desired system preferences.
Flake Issues
Problem: "error: flake 'path' does not provide attribute"
Symptoms:
- Cannot access flake outputs
- Attribute path errors
Solutions:
Check available outputs:
nix flake show
Verify the attribute path:
nix eval .#darwinConfigurations --apply builtins.attrNames
Check for typos in configuration names
Problem: Flake inputs won't update
Symptoms:
nix flake update
doesn't change versions- Stuck on old commits
Solutions:
Update specific inputs:
nix flake update nixpkgs home-manager
Clear flake registry cache:
rm -rf ~/.cache/nix/flake-registry.json
Force refresh:
nix flake update --refresh
SSH/SOPS Issues
Problem: Cannot decrypt secrets
Symptoms:
- "failed to decrypt" errors
- SOPS-encrypted files unreadable
Solutions:
Check SSH key is in ssh-agent:
ssh-add -l
Verify key is in
.sops.yaml
:sops --config .sops.yaml updatekeys secrets/secrets.yaml
Re-encrypt secrets with current keys:
sops --config .sops.yaml -r secrets/secrets.yaml
Using nh
for Troubleshooting
The nh
tool provides a better user experience for common NixOS/Darwin operations and is already configured in this setup.
System Operations
# Switch to new configuration (equivalent to darwin-rebuild/nixos-rebuild switch)
nh os switch
# Test configuration without switching
nh os test
# Boot into new configuration (NixOS only)
nh os boot
# Show what would be built/downloaded
nh os switch --dry
# Switch with detailed output
nh os switch --verbose
System Information
# Show system generations
nh os list
# Show current generation info
nh os list --current
# Show generation differences
nh os diff
# Show what packages would change
nh os diff --changes
Cleaning and Maintenance
# Clean old generations (disabled by default in config)
nh clean all
# Clean with specific parameters
nh clean all --keep 5 --keep-since 7d
# Just show what would be cleaned
nh clean all --dry
# Clean user profiles
nh clean user
# Clean system profiles
nh clean system
Home Manager Operations
# Switch home-manager configuration
nh home switch
# Test home-manager configuration
nh home test
# Show home-manager generations
nh home list
# Show home-manager differences
nh home diff
Search and Information
# Search for packages
nh search firefox
# Show package information
nh search --details firefox
# Search with specific attributes
nh search --json firefox | jq
Troubleshooting with nh
Debug failed switches:
nh os switch --verbose --show-trace
Check what's changed since last switch:
nh os diff --changes
Rollback to previous generation:
nh os list # Find previous generation number sudo /nix/var/nix/profiles/system-<number>-link/bin/switch-to-configuration switch
Clean up after failed builds:
nh clean all --dry # See what would be cleaned nh clean all --keep 3
Check flake status:
nh os switch --dry # Shows flake inputs and what would change
General Debugging
Check system status
# Using nh (recommended)
nh os switch --dry --verbose
# Traditional methods
# Darwin
darwin-rebuild --flake . switch --show-trace
# NixOS
nixos-rebuild --flake . switch --show-trace
Evaluate configuration without building
nix eval .#darwinConfigurations.darwin.config --json | jq .
Check derivation dependencies
nix show-derivation .#darwinConfigurations.darwin.system
Enable debug output
nix build --print-build-logs --verbose .#darwinConfigurations.darwin.system
Check for conflicting packages
# List all packages in environment
nix-env -q
# Check specific package source
nix eval .#darwinConfigurations.darwin.pkgs.packageName.meta
Performance Tips
Use binary caches: Ensure binary caches are configured in
nix.settings.substituters
Parallel builds: Set
nix.settings.max-jobs
appropriately for your hardwareBuild remotely: Consider using remote builders for resource-intensive builds
Pin dependencies: Use
flake.lock
to ensure reproducible buildsMinimal rebuilds: Structure modules to minimize unnecessary rebuilds
Getting Help
- Check logs: Always check build logs for specific error messages
- Search issues: Look for similar issues in relevant GitHub repositories
- Community: Ask in NixOS Discord, Reddit, or Discourse
- Documentation: Refer to official NixOS and Home Manager documentation
Remember to always backup your working configuration before making significant changes!