A living collection of tips to debug Nix derivations.

# More verbose traces

It is helpful to run nix build with the flags --show-trace --print-build-logs -v.

# breakpointHook

Instead of stopping when a failure occurs, breakpointHook will let you attach to the build process (the last line of the logs will print the command to do that).

nativeBuildInputs = [ breakpointHook ];

It is only available in Linux.

# Tracing all commands

Set NIX_DEBUG = 7; anywhere in your derivation. This sets -x on stdenv initialization and can be very verbose. Experiment with lower values to reduce verbosity.

# Tracing a specific value

builtins.trace takes a value, traces it, and returns its second value.

The lib.debug library functions in Nixpkgs provide a few more tools, e.g. to trace a value based on a condition (lib.debug.traceIf) or to trace a value and return it (lib.debug.traceVal).

# References