Skip to content


When writing a package definition, you will likely experience that you try to build the resulting derivation and it fails.

When this happens, one way of debugging the issue is to trigger a breakpoint at the point of failure, enter into the build environment and poke around to (hopefully) determine the cause of the issue.

First, add breakpointHook to the nativeBuildInputs list for your derivation. You will likely also have to add breakpointHook as an argument to the function which returns your derivation. E.g.:

skeleton for package
{ stdenv
, #....
, breakpointHook
stdenv.mkDerivation rec {
    # ...
    nativeBuildInputs = [
        # ...
    # ...

Then build your derivation once more. When it fails, breakpointHook will cause the process to pause and print a message mentioning the cntr command to run to enter the environment:

$ nix build .#libvfn
[1/0/1 built, 0.0 MiB DL] building libvfn-1.0.0 (buildPhase):    cntr attach -t command cntr-/nix/store/ijr3l638sv0ln4yzsczydz6xmnlx3fcp-libvfn

Run this command as root. cntr is not available in most distros, one way of getting it is via Nix, for example:

nix run github:NixOS/nixpkgs/nixos-22.11#cntr

cntr will exit in error, but reveal its location in the nix store, copy this path and re-run the command shown above:

/nix/store/inb57qmalb4knr6g3dl5k5y6gbbchl4h-cntr-1.5.1/bin/cntr attach -t command cntr-/nix/store/inb57qmalb4knr6g3dl5k5y6gbbchl4h-cntr-1.5.1/bin/cntr


Take care to update the store paths to point to your copy of cntr and your failing derivation!

Once inside the container, run the following to load the build environment:

/nix/store/inb57qmalb4knr6g3dl5k5y6gbbchl4h-cntr-1.5.1/bin/cntr exec

What now ?

The build sources are in /build. Try to build the package manually, step by step and see if there are any errors.

Note that the environment may hold flags which should be passed to the build tool. For instance, in meson projects, $mesonFlags hold all the flags which should be passed to meson setup.