As we introduce more checks and restrictions, this may result in some unexpected error messages for users that write their own derivations. What is causing the error may also not be very obvious from the, typically one line, error message. E.g., the
stdenv.mkDerivation may add some restrictions the user is not aware of.
Instead of printing a single one-liner stating something cannot be done, I suggest we introduce error codes and have a page in the manual listing with these codes and what they’re about.
What do you think about that?
Why wouldn’t we just explain what the error is about in the error message instead?
Yes, for “fatal” errors I don’t really see a disadvantage in multi-line explanations. We have those e.g. for meta checks already.
As an example, today I encountered some “not allowed to refer to the following paths” while checking the
staging-next branch. I am familiar with the parameter to
stdenv.mkDerivation for it, but apparently
stdenv.mkDerivation now contains some logic adding certain inputs to it as well. That wasn’t entirely obvious. I would appreciate if the error would then have a code so I can read up more on it. In this case it is too much to explain in the error message.
Why is it too much? I’d rather have a 50 line error message than an error code that indirectly leads to the 50 line error message.
I’d like to have the 50 line error message and an error code. Error codes are more searchable and allow people to refer to a specific error easily.
I was about to say, just like @ryantm, provide both.
Uniquely identifiable error codes will help in this day and age where the big search engines try too much to guess what you mean with the words you provide it. Only giving an error code will not help an end-user understand the issue, and will cause friction into trying to fix it.
Furthermore, I know this is not an issue (yet), but error codes will help in a future where the software (whichever here exactly) is localized or internationalized. A french-speaking user having some “n’est pas permis de faire référence à ces chemins” is a head-scratcher if and when they search for help and find few results, but “[nixpkgs-err-XYZ] n’est pas permis de faire référence à ces chemins” would allow less guessing around whether it translates to the same error or not.
Finally, two errors could realistically have different causes and, legitimately, the same exact error message. Using unique codes for each errors would allow differentiating which of the error message a user hit exactly.