Analysis

Nix scans all the entries and picks the first matching one. A match is just a check that there is a file or directory.

Eg:

$ mkdir -p foo/nixpkgs
$ NIX_PATH=./foo:nixpkgs=/proc nix-instantiate --eval --expr '<nixpkgs>'
/home/zimbatm/foo/nixpkgs

Now if I remove ./foo/nixpkgs:

$ rmdir foo/nixpkgs
$ NIX_PATH=./foo:nixpkgs=/proc nix-instantiate --eval --expr '<nixpkgs>'
/home/zimbatm/foo/nixpkgs
/proc

Another important thing is that if there are two nixpkgs entries, it will try them in order but also complain if the first entry doesn't match:

$ NIX_PATH=nixpkgs=/doesnt/exist:nixpkgs=/proc nix-instantiate --eval --expr '<nixpkgs>'
warning: Nix search path entry '/doesnt/exist' does not exist, ignoring
/proc

Conclusion

The issue with the old implementation is that the user's channel is not picked up if NIX_PATH already points to an existing nixpkgs. This can be fixed by changing the ordering instead:

I forgot that Eelco wanted to move away from the naked directory entries in NIX_PATH. Maybe nix search has a different resolution algorithm. But I don't see how to take a layered approach where the user can override the system channel, without using the naked directories. Otherwise we'll be in the situation where an error pops-up all the time for the users.

It doesn't really matter long-term since on the flakes branch, a command like nix build nixpkgs#hello searches the registry rather than NIX_PATH or channels. The temporary fix I just committed is to recognize channel directories generated by nix-channel and add each subdirectory to the default expression.