Troubleshooting

This page covers common issues you may encounter when installing, onboarding, or running NemoClaw, along with their resolution steps.

Get Help

If your issue is not listed here, join the NemoClaw Discord channel to ask questions and get help from the community. You can also file an issue on GitHub.

Installation

nemoclaw not found after install

If you use nvm or fnm to manage Node.js, the installer may not update your current shell’s PATH. The nemoclaw binary is installed but the shell session does not know where to find it.

Run source ~/.bashrc (or source ~/.zshrc for zsh), or open a new terminal window.

Installer fails on unsupported platform

The installer checks for a supported OS and architecture before proceeding. NemoClaw requires Linux Ubuntu 22.04 LTS or later. If you see an unsupported platform error, verify that you are running on a supported Linux distribution.

Node.js version is too old

NemoClaw requires Node.js 20 or later. If the installer exits with a Node.js version error, check your current version:

$ node --version

If the version is below 20, install a supported release. If you use nvm, run:

$ nvm install 20
$ nvm use 20

Then re-run the installer.

Docker is not running

The installer and onboard wizard require Docker to be running. If you see a Docker connection error, start the Docker daemon:

$ sudo systemctl start docker

On macOS with Docker Desktop, open the Docker Desktop application and wait for it to finish starting before retrying.

npm install fails with permission errors

If npm install fails with an EACCES permission error, do not run npm with sudo. Instead, configure npm to use a directory you own:

$ mkdir -p ~/.npm-global
$ npm config set prefix ~/.npm-global
$ export PATH=~/.npm-global/bin:$PATH

Add the export line to your ~/.bashrc or ~/.zshrc to make it permanent, then re-run the installer.

Port already in use

The NemoClaw gateway uses port 18789 by default. If another process is already bound to this port, onboarding fails. Identify the conflicting process, verify it is safe to stop, and terminate it:

$ lsof -i :18789
$ kill <PID>

If the process does not exit, use kill -9 <PID> to force-terminate it. Then retry onboarding.

Onboarding

Cgroup v2 errors during onboard

On Ubuntu 24.04, DGX Spark, and WSL2, Docker may not be configured for cgroup v2 delegation. The onboard preflight check detects this and fails with a clear error message.

Run the Spark setup script to fix the Docker cgroup configuration, then retry onboarding:

$ sudo nemoclaw setup-spark
$ nemoclaw onboard

Invalid sandbox name

Sandbox names must follow RFC 1123 subdomain rules: lowercase alphanumeric characters and hyphens only, and must start and end with an alphanumeric character. Uppercase letters are automatically lowercased.

If the name does not match these rules, the wizard exits with an error. Choose a name such as my-assistant or dev1.

Sandbox creation fails on DGX

On DGX machines, sandbox creation can fail if the gateway’s DNS has not finished propagating or if a stale port forward from a previous onboard run is still active.

Run nemoclaw onboard to retry. The wizard cleans up stale port forwards and waits for gateway readiness automatically.

Colima socket not detected (macOS)

Newer Colima versions use the XDG base directory (~/.config/colima/default/docker.sock) instead of the legacy path (~/.colima/default/docker.sock). NemoClaw checks both paths. If neither is found, verify that Colima is running:

$ colima status

Runtime

Sandbox shows as stopped

The sandbox may have been stopped or deleted. Run nemoclaw onboard to recreate the sandbox from the same blueprint and policy definitions.

Status shows “not running” inside the sandbox

This is expected behavior. When checking status inside an active sandbox, host-side sandbox state and inference configuration are not inspectable. The status command detects the sandbox context and reports “active (inside sandbox)” instead.

Run openshell sandbox list on the host to check the underlying sandbox state.

Inference requests time out

Verify that the inference provider endpoint is reachable from the host. Check the active provider and endpoint:

$ nemoclaw <name> status

If the endpoint is correct but requests still fail, check for network policy rules that may block the connection. Then verify the credential and base URL for the provider you selected during onboarding.

Agent cannot reach an external host

OpenShell blocks outbound connections to hosts not listed in the network policy. Open the TUI to see blocked requests and approve them:

$ openshell term

To permanently allow an endpoint, add it to the network policy. Refer to Customize the Network Policy for details.

Blueprint run failed

View the error output for the failed blueprint run:

$ nemoclaw <name> logs

Use --follow to stream logs in real time while debugging.