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
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
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.
Would you like access to private flakes and FlakeHub Cache?
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.