Troubleshooting

Start with nem doctor

nem doctor

nem doctor checks your setup — the build sandbox, shell integration, NEM_HOME, your nem.ver, and each configured catalog — and prints a remediation for anything that fails. It exits non-zero when a check fails, so it’s safe to run in CI.

A tool isn’t found after nem use

The shell integration probably isn’t active in your current session. Install it and reload:

nem activate
exec $SHELL

See Shell integration. In a non-interactive shell, run eval "$(nem shell-env)" instead.

A package can’t be found, or seems out of date

Refresh your catalogs, then search again:

nem catalog update
nem search <name>

For a single catalog, use nem update <name>. See Working with catalogs.

A source build fails in the sandbox

Source-built packages run in a sandbox that needs bubblewrap (bwrap) on Linux. Install it through your system package manager, or bypass the sandbox for one build with NEM_SANDBOX=0:

NEM_SANDBOX=0 nem use <package>

See Sandboxed builds.

Permission errors under ~/.nem

nem keeps its state in NEM_HOME (default ~/.nem). Make sure you own that directory and it’s writable — nem doctor reports this as the NEM_HOME check.

A malformed nem.ver

If nem reports syntax errors in nem.ver, fix the reported lines, then reformat the file with:

nem tidy