Changelog: JSON logging, a new experience around hash mismatches, and more

Logging provides a window into what a program is up to, and that window is never more crucial than when something has gone wrong and you need granular insight into what has happened and how you can fix it. In Nix, logging is generally most important during the realisation process, and ideally Nix would provide world-class build error logs. But historically this has not been seen as one of Nix’s strengths.

We’ve set out to change that, and we’re excited to announce that with the 3.3.1 release Determinate Nix now supports JSON logging for a small subset of error logs (with a larger subset to come soon). Adding this capability to Nix has also enabled us to dramatically upgrade the user experience around things like fixing hash mismatches.

Check out this video from Determinate Systems CEO and cofounder Graham Christensen for a quick overview:

Once you’ve done that, read on for some more in-depth information.

JSON logging

With Determinate Nix 3.3.1, Nix can now log some error messages as structured JSON. We’ve added this because JSON is generally more straightforward to parse by external tools.

At this stage, Nix provides JSON logs in one specific case: when Nix encounters a hash mismatch during a build. In the future we plan to enable JSON logging in more places but we think this is a good place to start.

Automatic fixes for hash mismatches

Seasoned users of Nix are likely all-too familiar with this log output:

error: hash mismatch in fixed-output derivation '/nix/store/2ybj73ri0dc9j28yzqlp7r1l2lpxnsxj-my-package.drv':
         specified: sha256-tmNn6/9jn/ansLI0QTfy6/fItRmBCOhb5AUOXbIWi24=
            got:    sha256-GzabkpW8L2UH4rzBkFdv61RoJl8DQlICqZvY9Ql1MAU=

This certainly does provide the information needed to fix the problem. But in order to actually extract the correct hash—the information you really want here—you need to parse this log as a string. You can do this with grep and other tools but let’s face it—it isn’t a whole lot of fun.

With JSON logging, however, Nix produces this instead:

{
  "v": "1",
  "c": "HashMismatchResponseEventV1",
  "drv": "/nix/store/2ybj73ri0dc9j28yzqlp7r1l2lpxnsxj-my-package.drv",
  "bad": [
    "sha256-tmNn6/9jn/ansLI0QTfy6/fItRmBCOhb5AUOXbIWi24="
  ],
  "good": "sha256-GzabkpW8L2UH4rzBkFdv61RoJl8DQlICqZvY9Ql1MAU="
}

You can parse JSON logs with tools like jq instead of, say, grep with a set of gnarly regular expressions.

Fix hashes using Determinate Nixd

Determinate Nixd, which comes installed with Determinate Nix, enables you to automatically fix mismatched hashes:

determinate-nixd fix hashes

Let’s say that you’ve just run nix build and gotten an error because, say, a vendor hash in a derivation building a Go application is wrong. If you run the command above, Determinate Nixd will prompt you to ask if you’d like to fix hash mismatches for you. If you say yes, Determinate Nixd fixes the relevant files in place; all you need to do is commit the changes and you’re ready to go.

Identify hash mismatches in GitHub Actions

While fixing hashes in your local development flows is nice, pretty much all of us forget to do this until it’s too late and our continuous integration workflows are unhappy with us. But with JSON logging now in Determinate Nix, we offer a solution to hash mismatches at that level as well.

If you’d like substantially improved hash mismatch reporting, all you have to do is use our nix-installer-action for GitHub Actions and enable Determinate Nix by setting determinate: true.

- uses: DeterminateSystems/nix-installer-action@main
  with:
    determinate: true

When you do that, you now get a GitHub-native notification rather than needing to dig through Nix error logs. This screenshot shows an example:

Note that this is now surfaced directly in the Git diff UI—and in an attention-grabbing red color to boot.

Automatic hash mismatches fixes in GitHub Actions

To finish drawing the owl, run determinate-nixd fix hashes --auto-apply on failure to fix pull requests automatically:

jobs:
  build:
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

      - uses: DeterminateSystems/nix-installer-action@main
        with:
          determinate: true

      - run: nix flake check -L

      - name: Fix hash mismatches
        if: failure()
        run: |
          determinate-nixd fix hashes --auto-apply

          if ! git diff --quiet; then
            git config user.name "github-actions[bot]"
            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
            git add .
            git commit -m "[dependabot skip] Fix hashes"
            git push
          fi

Ergonomic fixes

In addition to JSON logging and the new features that it has opened up, we’ve made some smaller improvements that we hope you’ll like as well.

Better suggestions for untracked files

When you use flakes, Nix needs to work closely with Git to function properly. Sometimes there are untracked changes in your repository that keep Nix from working as expected. For years, Nix has emitted this log message when that happens:

error: path '/nix/store/0ccnxa25whszw7mgbgyzdm4nqc0zwnm8-source/flake.nix' does not exist

That’s… pretty opaque. It’s not clear why that file existing is somehow important and it doesn’t tell you how to fix the problem.

With Determinate Nix 3.3.1, you now see an error message like this instead:

error: Path 'flake.nix' in the repository "/home/justme/my-project" is not tracked by Git.

       To make it visible to Nix, run:

       git -C "/home/justme/my-project" add "flake.nix"

Nix now provides not just a better error message but also actionable information that you can use to remedy the situation. This has been a paper cut for Nix users for years and we’re really happy to put it behind us for good.

nix profile install is now nix profile add

The nix profile command has an install subcommand that you can use to add a package to the current Nix profile. This command works as expected but we’ve always felt like “install” isn’t really the right verb—and many of our users have shared that sentiment.

In Determinate Nix 3.3.1, this has been replaced with an add subcommand:

nix profile add nixpkgs#ponysay

Running nix profile install still works as an alias, but we do recommend switching any scripts over to the add subcommand now. Like the untracked files error message, this isn’t an earth-shattering change but it still feels good to bring Nix more in line with users’ expectations.

How to upgrade or install

If you already have Determinate Nix installed, you can upgrade to 3.3.1 with one Determinate Nixd command:

sudo determinate-nixd upgrade

If you don’t yet have Determinate Nix installed, you can install it on macOS using our graphical installer:

Install Determinate Nix on macOS now

Apple Silicon and Intel

On Linux:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | \
  sh -s -- install --determinate

On NixOS, we recommend using our dedicated NixOS module.

More to come

Nix now has the necessary code paths to output JSON logs wherever they may be needed. We’ve started modestly with adding such logs, but even this modest beginning provides some powerful new workflows for Nix. We have some ideas for other areas where JSON logs can open up new paths in Nix and we’ll be exploring those soon.

On top of that, we’ve provided some ergonomic changes that address small but long-standing and substantial user experience issues in Nix. And we plan to tackle a few more issues along these lines in the coming weeks.

That’s it for now! Stay tuned here on the blog for more advancements in the whole experience around using Nix.