How to Actually Read Nix Error Messages (Without Crying)

1. Infinite Recursion Encountered

This means Nix tried to evaluate an attribute that depends on itself. Common causes: using self or super incorrectly in an overlay, or a callPackage where an attribute refers back to the derivation being defined.

# Classic trap: referring to 'pkgs' before it's fully constructed
let
  pkgs = import <nixpkgs> { overlays = [ overlay ]; };
  overlay = final: prev: {
    myPkg = pkgs.stdenv.mkDerivation { ... }; # ← should be 'final.stdenv'
  };
in pkgs

Debug strategy: Add --show-trace to your nix build or nix eval call. The trace will point you to exactly which attribute triggered the cycle.

2. Value Is Not a Function / Not an Attribute Set

Nix's type system is lazy. Errors only surface during evaluation. This means you passed something of the wrong shape. Usually a missing argument, a typo in an attribute name, or forgetting to apply a function.

# Often caused by:
let
  f = { foo }: foo + 1;
in
f 42  # passing an int to a function expecting an attrset

When the error says "value is not an attribute set" and points into nixpkgs, it usually means you've passed a derivation where a set of options was expected, or vice versa. For instance, calling pkgs.python3.withPackages and forgetting the lambda.

3. Attribute Not Found

The most common error for nixpkgs newcomers. You're trying to access an attribute that doesn't exist on a set. Check spelling, check whether the package is in the right channel, and make sure you haven't confused a package set (like pkgs.python3Packages) with a package (pkgs.python3).

error: attribute 'pythonPackages' missing

# The attribute set 'pkgs' does have this path, just named differently:
# pkgs.python3Packages.requests   ← correct
# pkgs.pythonPackages.requests    ← does not exist

4. Builder Failed with Exit Code N

This is a build-time error, not an evaluation error. Nix successfully evaluated your derivation, but the build script failed. The error message itself is almost never useful. The real information is in the build log.

error: builder for '/nix/store/...-my-package-1.0.drv' failed with exit code 1
       For full logs, run:
         nix log /nix/store/...-my-package-1.0.drv

Critical: Always run nix log immediately. The exit code alone tells you nothing. The log tells you everything: missing headers, failed tests, network errors, wrong phase outputs.

5. Hash Mismatch

A fetchurl, fetchgit, or similar fetcher got content that doesn't match the declared hash. This is either a stale hash in your derivation, or the upstream source changed in place (which happens more than you'd hope).

error: hash mismatch in fixed-output derivation '/nix/store/...':
         specified: sha256-AAAA...
         got:       sha256-BBBB...

Fix it by updating the hash. The "got" value is the correct one. Copy it into your derivation. For fetchgit, also update the rev if the source moved.

Leveling Up: A Better REPL

The default nix repl is barebones. After months of typing :lf . and manually navigating attribute sets, I built a custom repl.nix that preloads all my hosts, configs, and helper functions. It looks like this:

# filename: repl.nix
{
  # Pass your host name when starting the repl
  host ? "xenomorph",
  ...
}:
let
  flake = builtins.getFlake (toString ./.);
  inherit (flake.inputs.nixpkgs) lib;
in
{
  inherit lib;
  inherit (flake) inputs;

  # Quick access to current host
  c = flake.nixosConfigurations.${host}.config;
  config = c;
  co = c.custom;
  pkgs = flake.nixosConfigurations.${host}.pkgs;

  # Helper functions for debugging
  keys = lib.attrNames;                    # List all attributes in a set
  deps = pkg: map (p: p.name or "unknown") (pkg.buildInputs ++ pkg.nativeBuildInputs or []);

  # Find where an option is defined (filters out nixos internals)
  where = path: let
    opt = lib.attrByPath (lib.splitString "." path) null
          flake.nixosConfigurations.${host}.options;
    decls = if opt != null && opt ? files then opt.files else [];
    isMine = f: !(lib.hasInfix "nixos/modules/" (toString f));
    in lib.filter isMine decls;

  # Reload without exiting repl
  reload = import ./repl.nix { inherit host; };
}
// flake.nixosConfigurations  # Merge in all host configs

Why this is better:

• keys pkgs: Instead of typing :p pkgs and scrolling through 50,000 attributes, get a clean list
• where "services.nginx.virtualHosts": Find exactly which file defines that option, filtered to ignore nixpkgs internals
• deps pkgs.hello: See build inputs for any package without digging through nixpkgs source
• c / config / co: Short aliases for the current host's config and custom options
• reload: Re-import the repl.nix without exiting (great when you're editing the repl itself)

Using it with a helper script:

#!/usr/bin/env bash
if [[ -f repl.nix ]]; then
  nix repl --arg host '"xenomorph"' --file ./repl.nix "$@"
else
  # Fallback to regular repl if not in a project with repl.nix
  nix repl .
fi

Now when I hit an error, I can jump into the repl and inspect values immediately:

nix-repl> c.services.nginx.enable
true

nix-repl> where "services.nginx.virtualHosts"
[ /home/k1ng/nix/dotfiles.nix/modules/web/nginx.nix ]

nix-repl> keys co.persist.home
directories files

nix-repl> deps pkgs.neovim
[ "libuv" "msgpack" "tree-sitter" ... ]

The inspiration for this came from Brian McGee's post about Nix's slow feedback loop. The REPL becomes a real debugging tool, not just a calculator.

Pro tip: The nix repl is criminally underused. You can load any flake, inspect attribute values, call functions, and test expressions interactively, all without triggering a full build.