New detailed troubleshooting section in the manual

I think we need a new section in the manual detailing much of the repetitious troubleshooting going on here (see example in appendix 2).

I would like it to contain all errors that has been shared with the list at least twice.

Help compiling such a list of those would be appreciated (see a start in appendix 1)

substitute: guix substitute: warning: while fetching 'https://mirror.hydra.gnu.org/nix-cache-info': 504 ("Gateway Time-out")
warning: downgrade bla bla after binary installation before system init/reconfigure

Guix packages:

After installing a package it is not found:

bash: test-not-found: command not found
try locating the bin with: sudo updatedb && locate test-not-found
If it found something the package is probably correctly installed but you have an incorrect $PATH.

Guix build

Source URL not found (404 errors, etc.)

When looking for a file that Guix is trying to download but which is no
longer available at the expected URL, I normally just do a web search
for the file name, in this case "texlive-20170524-extra.tar.xz".  Any
site will do.  It needn't be a site you trust, because Guix always
checks the sha256 hash anyway.

If you "guix download" a file with the right name but the wrong
contents, it will be successfully added to the store, but with the wrong
hash string in the file name in /gnu/store, so nothing will ever use it.
When you attempt to restart the build that failed, it will again try to
download it, because the file it needs is not in the store.  The bogus
file will be deleted the next time to run "guix gc".

Hash mismatch

sha256 hash mismatch for output path '/gnu/store/bjpalrv9f49d2k40p7ga0y6dwdys9w5j-bzip2-1.0.6.tar.gz'

expected: *****************************************

actual: *********************************************

cannot build derivation: ***************************

Bad Read-Header-Line header: #<eof>

This is really probably a 404. (and a bug in guix for not yet handling this correctly and throwing a backtrace instead)
Find a working substitute on another substitute server or build the package yourself by specifying --fallback.

guix system init

parenthesis mismatch error:

check your parenthesis

nano: guide...
emacs: install paredit and do ...

module missing

add the relevant missing module. If not certain which to add either look in the manual or search the source tree in http://git.savannah.gnu.org/cgit/guix.git/ or in a local git checkout (run git clone --depth=1 https://git.savannah.gnu.org/git/guix.git) with find

invalid field specifier

often points to the start of the offending s-_expression_. (this is most often happening with service definitions which can be hard to get right for newcomers)

Start by checking any newly changed fields - did you follow the manual correctly?
If this does not help try firing up the REPL with

$ guile
And type (use-modules bla bla
Then paste the service definitions one by one
If you need more help as on IRC or help-guix.

gnu/services.scm:703:40: In procedure service-kind: Wrong type argument:

The (services) section (which is a list of service records) of your operating-system record is incorrect.
See bug #31885 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=31885

compiling the world

if unable to find substitutes guix will AUTOMATICALLY fall back to building from source without asking you for a go-ahead.
The only way to avoid this is to minimize the packages specified in the config.scm (general advice as it tend to make guix init/reconfigure take a long time) and make sure you have access to substitutes.

From:	swedebugia
Subject:	New detailed troubleshooting section in the manual
Date:	Sun, 4 Nov 2018 09:04:37 +0100