---

name: debugging description: Troubleshoot Nix evaluation and build errors

Debugging

Evaluation Debugging

Using builtins.trace

Add trace statements to see values during evaluation:

Copylet
  myValue = builtins.trace "myValue is: ${toString someVar}" someVar;
in
# myValue will print during evaluation

For complex values:

Copybuiltins.trace (builtins.toJSON someAttrSet) someAttrSet

Using nix eval

Test expressions without building:

Copy# Evaluate a specific option
nix eval .#nixosConfigurations.nixdev.config.networking.hostName

# Check if something evaluates
nix eval .#nixosConfigurations.nixdev.config.services.nginx.enable

# Evaluate with trace output visible
nix eval .#nixosConfigurations.nixdev.config.system.build.toplevel --apply 'x: "ok"'

Show trace on error

Copynix build .#nixosConfigurations.nixdev.config.system.build.toplevel --show-trace

Common Errors

Infinite recursion

Error: infinite recursion encountered

Causes:

• Circular imports between modules
• Option depending on itself
• Config referencing options that reference config

Fix: Check for circular dependencies in imports or option definitions.

Attribute not found

Error: attribute 'foo' missing

Causes:

• Typo in attribute name
• Missing import
• Wrong option path

Fix:

Copy# List available attributes
nix eval .#nixosConfigurations.nixdev.config.services --apply 'builtins.attrNames'

Type mismatch

Error: value is a string while a list was expected

Causes:

• Wrong type for option
• Incompatible merge of values

Fix: Check option type definition and provided value.

Assertion failed

Error: assertion ... failed

Causes:

• Configuration constraint not met
• Missing required option

Fix: Read the assertion message, provide required configuration.

Build Debugging

View build logs

Copy# For a failed derivation
nix log /nix/store/...-derivation.drv

# Or from error output
nix log <drv-path-from-error>

Build with verbose output

Copynix build .#package -L

Enter build environment

Copynix develop .#nixosConfigurations.nixdev.config.system.build.toplevel

Module Debugging

Check if module is imported

Copynix eval .#nixosConfigurations.nixdev.config.services.myService.enable

List all options in a namespace

Copynix eval .#nixosConfigurations.nixdev.options.services.myService --apply 'builtins.attrNames'

Check option definition location

Copynix eval .#nixosConfigurations.nixdev.options.services.nginx.enable.definitionsWithLocations

Flake Debugging

Check flake syntax

Copynix flake check --no-build

Show flake structure

Copynix flake show

Evaluate specific output

Copynix eval .#nixosConfigurations --apply 'builtins.attrNames'
nix eval .#homeConfigurations --apply 'builtins.attrNames'

Quick Diagnostics