Troubleshooting Nix problems

Common issues encountered when using the Nix development shell, and how to resolve them.

`command not found: nix` after a macOS update

If a shell suddenly can't find nix at all:

$ nix develop
zsh: command not found: nix

then Nix is almost certainly still installed — only the shell hook that puts it on your PATH is gone. Confirm that first:

ls -l /nix/var/nix/profiles/default/bin/nix

If that exists, the installation is fine and this is purely a PATH problem.

Why it happens

The installer does not touch your dotfiles. Instead it sources a setup script from the Nix store by editing system-wide rc files:

Shell	File the installer edits
bash	`/etc/bashrc`, `/etc/bash.bashrc`
zsh	`/etc/zshrc`
fish	`$__fish_sysconf_dir/conf.d/nix.fish`

macOS manages /etc/zshrc, so an OS update can replace it with the vendor copy and silently drop the Nix block. /etc/bashrc and the fish file usually survive, which is why the breakage often shows up in zsh only. You can verify this by diffing against the backup the installer left behind:

diff /etc/zshrc /etc/zshrc.backup-before-nix

If they are identical, the Nix snippet was wiped. This is upstream issue NixOS/nix#3616.

Fix

To unblock the current shell:

. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh

For a permanent fix, add the snippet to your user rc file rather than restoring /etc/zshrc — user dotfiles are not clobbered by OS updates:

cat >>~/.zshrc <<'EOF'

# Nix
if [ -e '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh' ]; then
  . '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh'
fi
# End Nix
EOF

The scripts guard against double-sourcing via __ETC_PROFILE_NIX_SOURCED, so this is safe even if a system-wide hook is later restored.

Note

/etc/zshrc and ~/.zshrc are only read by interactive zsh. If the snippet is present but zsh -c '…', a script, or an IDE terminal still can't find nix, that shell is non-interactive — put the snippet in ~/.zshenv instead.

Git worktrees

If nix develop fails with an error like:

error:
       … while fetching the input 'git+file:///path/to/rippled'

       error: opening Git repository "/path/to/rippled": unsupported extension name extensions.relativeworktrees (libgit2 error code = 6)

then your Nix is linked against a libgit2 older than 1.9.4. Git 2.48+ writes the extensions.relativeWorktrees config entry when a worktree is created with relative paths (git worktree add --relative-paths, or with worktree.useRelativePaths=true), and older libgit2 versions refuse to open a repository that uses it. Nix uses libgit2 to read the flake, so evaluation fails.

Important

This entry is written to the shared repository config, so once any relative worktree exists, nix develop fails in the main checkout too — not just inside the worktree.

Workarounds

These work today, with any Nix version:

bypass libgit2 with a path: flakeref: nix develop "path:$PWD" (note: this copies the working tree to the store and ignores .gitignore); or
create worktrees with absolute paths (omit --relative-paths); or
clear the extension if you don't need relative worktrees: git config --unset extensions.relativeWorktrees.

Permanent fix

The fix is in libgit2 1.9.4, so the real solution is a Nix that links against libgit2 1.9.4 or newer. Check which version yours links against:

nix-store -qR "$(readlink -f "$(command -v nix)")" | grep libgit2

Warning

nix upgrade-nix does not help yet. It installs the build from the official nix-fallback-paths, which is still linked against libgit2 1.9.2 — there is no new upstream Nix release with the fix. (On some systems that build is even the exact store path you already have, making the upgrade a no-op.)

nixpkgs has already rebuilt Nix against the fixed libgit2 (e.g. nix-2.34.7+1), so the cleanest path is to reinstall Nix using your usual installation method once it picks up that rebuild, then re-run the grep libgit2 check above to confirm it reports 1.9.4 or newer.

Until then, prefer the workarounds above.

4.5 KiB Raw Blame History