`nix search` error messages are unhelpfull #985

New issue

Open

opened 2025-09-03 17:53:03 +00:00 by icewind · 1 comment

icewind commented

2025-09-03 17:53:03 +00:00

the nix search behavior isn't the most intuitive, users are likely to (reasonably) assume that nix search kate would search for kate.

The error that gives:

error: Must provide at least one regex! To match all packages, use 'nix search <installable> ^'.

with "installable" being an unexplained term, the user would try nix search kate ^ which just results in

error: cannot find flake 'flake:kate' in the flake registries

Leaving the user with nothing but frustration.

I've both gone trough this myself and seen other users go trough it.

Describe the solution you'd like

The error message for nix flake search <term> could check if <term> is an installable and if not, list the available installables and suggest search trough one of those.

Making the error something like

error: "kate" is not an installable

The following installables are registered

- nixpkgs
- nixos-hardware
- home-manager

To search for the package "kate" in one of those installables, use `nix search <installable> kate`

would hopefully be enough to teach users how to use the command.

Additionally, the output of nix search <installable> <regex> could list the available installables if the provided one is not found.

Describe alternatives you've considered

The term "installable" could be changed to something less likely to be confused with "package"

nix search kate could instead default to search either a default installable (nixpkgs) or all installables. But that would be breaking compatibility.

## Is your feature request related to a problem? Please describe. the `nix search` behavior isn't the most intuitive, users are likely to (reasonably) assume that `nix search kate` would search for kate. The error that gives: ``` error: Must provide at least one regex! To match all packages, use 'nix search <installable> ^'. ``` with "installable" being an unexplained term, the user would try `nix search kate ^` which just results in ``` error: cannot find flake 'flake:kate' in the flake registries ``` Leaving the user with nothing but frustration. I've both gone trough this myself and seen other users go trough it. ## Describe the solution you'd like The error message for `nix flake search <term>` could check if `<term>` is an installable and if not, list the available installables and suggest search trough one of those. Making the error something like ``` error: "kate" is not an installable The following installables are registered - nixpkgs - nixos-hardware - home-manager To search for the package "kate" in one of those installables, use `nix search <installable> kate` ``` would hopefully be enough to teach users how to use the command. Additionally, the output of `nix search <installable> <regex>` could list the available installables if the provided one is not found. ## Describe alternatives you've considered The term "installable" could be changed to something less likely to be confused with "package" `nix search kate` could instead default to search either a default installable (nixpkgs) or all installables. But that would be breaking compatibility.

jade added the

Area/flakes

Area/cli

labels

2025-09-03 20:28:23 +00:00

jade commented

2025-09-03 22:34:34 +00:00

Owner

i agree that the error could be better written, but one specific clarification i need to make is that "installable" is a very specific term of art defined in the nix3-flake(1) manual page. it would be incorrect to not reference it, but the error message should educate the user as to the general nature of how to use the command in addition to still calling it an installable. it is confusing though to use installable to mean attrset of packages, i will say that, as normally it names one derivation.

as for the suggestion to mention the existing installables, this is not possible. if we were to dump those for flakes that would mean dumping the flake registry (which isn't even complete bc you could write github:nixos/nixpkgs also!), which is much too large to be useful to the user in an error message. see the output of nix registry list. also, because it does take an installable, you could write -f '<nixpkgs>' instead of flake stuff.

all of this to say: you're right about it being confusing and a trivial rewording would help a lot, but it's a bit more nuanced as to how to actually do the rewording.

okay here's the deal: nix search was rewritten 5 years ago to not work well anymore in nix 2.4, when it was rewritten to be totally inseparably tangled with flakes and if I recall correctly also became slow at that point. my practical advice is to use nix-index instead. i agree that the error could be better written, but one specific clarification i need to make is that "installable" is a very specific term of art defined in the nix3-flake(1) manual page. it would be incorrect to not reference it, but the error message should educate the user as to the general nature of how to use the command in addition to still calling it an installable. it *is* confusing though to use installable to mean attrset of packages, i will say that, as normally it names one derivation. as for the suggestion to mention the existing installables, this is not possible. if we were to dump those for flakes that would mean dumping the flake registry (which isn't even complete bc you could write github:nixos/nixpkgs also!), which is much too large to be useful to the user in an error message. see the output of nix registry list. also, because it does take an installable, you could write `-f '<nixpkgs>'` instead of flake stuff. all of this to say: you're right about it being confusing and a trivial rewording would help a lot, but it's a bit more nuanced as to how to actually do the rewording.