Skip to content

FAQ: Common Errors

Overview

Symptom → likely cause → wiki leaf. Classify the failure first: eval (before “building …”), build (builder exit / FOD hash mismatch), activation (switch/test after the closure exists), or boot (new generation will not reach multi-user). Full checklists and recovery: Troubleshooting.

Details

Evaluation

Symptom (approx) Likely cause Read
experimental Nix feature '…' is disabled Need nix-command and/or flakes in experimental-features CLI cheatsheet, nix.conf knobs, Feature flags overview
infinite recursion encountered Plain if config.… around config that also sets that option; value cycle; bad rec / self-shadowing mkIf / mkMerge / mkOrder, Debugging evaluation, Anti-patterns
“The option … does not exist”, “is not a …”, conflicting / multiple definitions Typo’d option path, wrong type, incompatible merge Troubleshooting, Options and types, NixOS options patterns
Option missing in docs / wrong defaults vs your pin; hunting services in Nixpkgs manual Wrong manual or channel; search not matched to pin Reading manuals and search, Options and types
attribute '…' missing Typo’d attr path; flake pure eval (currentSystem, <nixpkgs>); lazy set not populated yet Pure eval and impure, Debugging evaluation
impure evaluation is not allowed / forbidden builtins under flakes Undeclared inputs, getEnv, mutable paths, unpinned fetches Pure eval and impure
Long “eval” with no .drv yet; CI eval suddenly needs builds Import-from-derivation (eval reads a store path from another derivation) Import-from-derivation, Lazy trees and eval perf, Debugging evaluation
New file on disk but flake build ignores it Git flake copies only indexed files (git add / commit); untracked or .gitignored paths invisible Pure eval and impure (Git flakes and the source tree)

Install / auth

Symptom (approx) Likely cause Read
Wrong nix --version / odd defaults; two nix on PATH; mixed upgrade/uninstall breakage Multiple installers (CppNix / Lix / Determinate) or foreign curl install on NixOS Installers and Nix variants
401 / 404 on private github: / gitlab: flake input (esp. CI); works locally, fails on runner Missing/wrong access-tokens / netrc-file; token not injected in CI Private flakes and CI, Access tokens

Build

Symptom (approx) Likely cause Read
hash mismatch in fixed-output derivation Upstream tarball/git content changed; wrong declared outputHash Fixed-output derivation, Debugging builds
Haskell Cabal version-bound / dependency check fails Set pins one version per name; need jailbreak / doJailbreak (still no Cabal solver) Haskell packaging
Gradle deps / mitmCache fail; PHP vendorHash mismatch Stale deps.json / Composer lock hash; refresh FOD pins JVM / PHP and others, Fixed-output derivation
builder for … failed with exit code N / builder failed Compile/test/sandbox failure in a phase Debugging builds, Troubleshooting
No space left on device (often /tmp or build dir) Disk full on /, /nix, or TMPDIR Troubleshooting, Garbage collection
ignoring untrusted substituter / cannot add substituter Unprivileged user; URL not in daemon trusted-substituters (do not widen trusted-users casually) Trusted users and substituters, nix.conf knobs

Store / disk (eval or build)

Symptom (approx) Likely cause Read
Missing store paths, hash mismatch on realized paths, corrupt closure (often after crash) Store corruption; partial download Troubleshooting (--repair, nix-store --verify)
Paths vanish after GC; “path is no longer valid” Unrooted paths collected; missing profile/GC root Garbage collection, Troubleshooting

Activation

Symptom (approx) Likely cause Read
Rebuild exits during switch/test; “Failed to start …” while nixos-rebuild still running Activation script or unit restart during switch-to-configuration Troubleshooting, Activation script
Rebuild succeeds but unit is failed or in a restart loop Systemd unit failure after activation (config/runtime, not the activate script itself) Troubleshooting, Systemd integration
System units updated but systemd --user units unchanged after switch Documented limitation — rebuild does not start/stop user services Troubleshooting
darwin-rebuild / flake: attribute '…' missing for host name --flake .#name ≠ darwinConfigurations key; ComputerName vs LocalHostName (scutil) nix-darwin

Boot / images (after successful build/activation)

Symptom (approx) Likely cause Read
Unbootable after switch — hang, emergency shell, reboot loop Bad bootloader/kernel/initrd/generation default Rollbacks, Troubleshooting
Need previous generation from bootloader / nixos-rebuild --rollback Bad generation still selected as default Rollbacks
AMI / GCE / Azure image confusion; nixos-generators vs build-image Prefer nixos-rebuild build-image --image-variant … (25.05+); query AMIs, don’t hardcode IDs Amazon / GCE / Azure

Examples

Re-run eval with a full stack when the error site is unclear:

nixos-rebuild switch --show-trace
# or
nix build .#pkg --show-trace

Build side: stream logs with -L / --print-build-logs, then nix log /nix/store/….drv — see Debugging builds.

Auth side (private flake inputs): confirm effective tokens with config inspection, not by echoing secrets — see Access tokens and Private flakes and CI.

See also

References