dotfiles/.agents/skills/nixos-best-practices/rules/common-mistakes.md

title, impact, impactDescription, tags

title	impact	impactDescription	tags
Common Configuration Mistakes	HIGH	Prevents the most frequently made configuration errors	mistakes,pitfalls,errors,checklist

Why This Matters

Understanding common mistakes helps avoid them, saving time and preventing configuration errors.

Mistake 1: Overlay in Wrong Location

Symptom

Package not found even though overlay is defined.

Cause

Overlay defined in home.nix when useGlobalPkgs = true.

Solution

Move overlay to host's home-manager configuration block.

# ❌ WRONG
# home-manager/home.nix
{
  nixpkgs.overlays = [ inputs.overlay.overlays.default ];
}

# ✅ CORRECT
# hosts/home/default.nix
{
  home-manager.nixpkgs.overlays = [ inputs.overlay.overlays.default ];
}

See: overlay-scope.md

Mistake 2: Forgetting specialArgs

Symptom

undefined variable 'inputs' error.

Cause

Not passing inputs via specialArgs.

Solution

Add specialArgs = { inherit inputs; }.

# ❌ WRONG
outputs = { self, nixpkgs, home-manager }:
{
  nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
    modules = [ ./hosts/myhost ];
  };
}

# ✅ CORRECT
outputs = { self, nixpkgs, home-manager, ... }@inputs:
{
  nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
    specialArgs = { inherit inputs; };
    modules = [ ./hosts/myhost ];
  };
}

See: flakes-structure.md

Mistake 3: Editing hardware-configuration.nix

Symptom

Hardware changes lost after running nixos-generate-config.

Cause

Manually editing generated file.

Solution

Put custom config in default.nix, not hardware-configuration.nix.

# ❌ WRONG: Editing hardware-configuration.nix
# hosts/laptop/hardware-configuration.nix
{ config, lib, pkgs, modulesPath, ... }:
{
  # My custom kernel parameters (will be lost!)
  boot.kernelParams = [ "intel_iommu=on" ];

  # Generated hardware config...
}

# ✅ CORRECT: Custom config in default.nix
# hosts/laptop/default.nix
{
  imports = [ ./hardware-configuration.nix ];

  # Custom kernel parameters (safe!)
  boot.kernelParams = [ "intel_iommu=on" ];
}

See: host-organization.md

Mistake 4: Duplicate Package Declarations

Symptom

Package installed multiple times or conflicts.

Cause

Same package in both system and Home Manager config.

Solution

Install in appropriate location only.

# ❌ WRONG: Same package in both places
# hosts/base.nix
environment.systemPackages = with pkgs; [ firefox ];

# home-manager/home.nix
home.packages = with pkgs; [ firefox ];  # Duplicate!

# ✅ CORRECT: Choose one location
# User apps in Home Manager
home.packages = with pkgs; [ firefox ];

See: package-installation.md

Mistake 5: Not Following nixpkgs

Symptom

Slow builds, inconsistent packages.

Cause

Multiple independent nixpkgs instances.

Solution

Use .follows for dependency inputs.

# ❌ WRONG: Independent nixpkgs
inputs = {
  nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  home-manager.url = "github:nix-community/home-manager/release-25.05";
  # home-manager will use its own nixpkgs!
};

# ✅ CORRECT: Follow nixpkgs
inputs = {
  nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  home-manager.url = "github:nix-community/home-manager/release-25.05";
  home-manager.inputs.nixpkgs.follows = "nixpkgs";
};

See: flakes-structure.md

Mistake 6: Mixing System and User Concerns

Symptom

User-specific config in system files or vice versa.

Cause

Not understanding NixOS vs Home Manager responsibilities.

Solution

System config in NixOS, user config in Home Manager.

# ❌ WRONG: User config in system
# hosts/base.nix
{
  # User's git config (should be in Home Manager)
  programs.git = {
    enable = true;
    userName = "john";
    userEmail = "john@example.com";
  };
}

# ✅ CORRECT: User config in Home Manager
# home-manager/home.nix
{
  programs.git = {
    enable = true;
    userName = "john";
    userEmail = "john@example.com";
  };
}

See: package-installation.md

Mistake 7: Forgetting to Rebuild

Symptom

Changes don't appear after editing config.

Cause

Editing config but not running rebuild.

Solution

Always rebuild after config changes.

# After editing NixOS config
sudo nixos-rebuild switch --flake .#hostname

# After editing Home Manager config (standalone)
home-manager switch --flake .#hostname

# When using NixOS-integrated Home Manager
sudo nixos-rebuild switch --flake .#hostname

Mistake 8: Overriding systemPackages Multiple Times

Symptom

Some packages disappear after adding others.

Cause

Multiple environment.systemPackages assignments.

Solution

Use single list or mkBefore/mkAfter.

# ❌ WRONG: Multiple assignments
environment.systemPackages = with pkgs; [ vim git ];
environment.systemPackages = with pkgs; [ htop ];  # Overwrites!

# ✅ CORRECT: Single list
environment.systemPackages = with pkgs; [
  vim
  git
  htop
];

# ✅ ALSO CORRECT: Use mkBefore/mkAfter
environment.systemPackages = with pkgs; [ vim git ];
environment.systemPackages = mkAfter [ pkgs.htop ];

Mistake 9: Hardcoding Paths

Symptom

Config breaks on different machines.

Cause

Using absolute paths instead of Nix paths.

Solution

Use relative paths or Nix constructs.

# ❌ WRONG: Absolute path
{ pkgs, ... }:
{
  environment.systemPackages = [
    "/home/john/my-app/bin/my-app"  # Only works for john!
  ];
}

# ✅ CORRECT: Use Nix package
{ pkgs, ... }:
{
  environment.systemPackages = [ pkgs.my-app ];
}

# ✅ OR: Use path from flake
{ ... }:
{
  environment.systemPackages = [
    (pkgs.callPackage ./local-packages/my-app { })
  ];
}

Mistake 10: Not Using Flake References

Symptom

Can't use packages from flake inputs.

Cause

Not passing inputs or using wrong reference.

Solution

Use inputs.* syntax.

# ❌ WRONG: Trying to use input package
{ pkgs, ... }:
{
  environment.systemPackages = [
    unfire-overlay  # Where does this come from?
  ];
}

# ✅ CORRECT: Use input reference
{ pkgs, inputs, ... }:
{
  environment.systemPackages = [
    inputs.unfire-overlay.packages.${pkgs.system}.default
  ];
}

Quick Checklist

Before committing config changes:

• Overlay in correct location for useGlobalPkgs setting
• inputs passed via specialArgs if needed
• Not editing hardware-configuration.nix
• No duplicate package declarations
• Following nixpkgs for dependency inputs
• System config separate from user config
• Tested with rebuild
• Using Nix paths, not absolute paths
• Correct input references for flake packages