diff --git a/README.md b/README.md index 03087ffc4c3..16e63abded1 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,9 @@ The script installs Node.js if it is not already present, then runs the guided o $ curl -fsSL https://nvidia.com/nemoclaw.sh | bash ``` +If you use nvm or fnm to manage Node.js, the installer may not update your current shell's PATH. +If `nemoclaw` is not found after install, run `source ~/.bashrc` (or `source ~/.zshrc` for zsh) or open a new terminal. + When the install completes, a summary confirms the running environment: ``` @@ -191,6 +194,7 @@ Refer to the documentation for more information on NemoClaw. - [Inference Profiles](https://docs.nvidia.com/nemoclaw/latest/reference/inference-profiles.html): NVIDIA cloud inference configuration - [Network Policies](https://docs.nvidia.com/nemoclaw/latest/reference/network-policies.html): egress control and policy customization - [CLI Commands](https://docs.nvidia.com/nemoclaw/latest/reference/commands.html): full command reference +- [Troubleshooting](https://docs.nvidia.com/nemoclaw/latest/reference/troubleshooting.html): common issues and resolution steps ## License diff --git a/docs/index.md b/docs/index.md index b4dc9bf57d1..740d901eaed 100644 --- a/docs/index.md +++ b/docs/index.md @@ -236,6 +236,7 @@ Architecture Commands Inference Profiles Network Policies +Troubleshooting ``` ```{toctree} diff --git a/docs/monitoring/monitor-sandbox-activity.md b/docs/monitoring/monitor-sandbox-activity.md index f7db139b64a..ab071e5f3ed 100644 --- a/docs/monitoring/monitor-sandbox-activity.md +++ b/docs/monitoring/monitor-sandbox-activity.md @@ -47,7 +47,7 @@ Key fields in the output include the following: - Blueprint run ID, which is the identifier for the most recent blueprint execution. - Inference provider, which shows the active provider, model, and endpoint. -If you run `openclaw nemoclaw status` from inside the sandbox, the command detects the sandbox context and reports it. Host-level sandbox and inference details are not available from within the sandbox. Run `openshell sandbox status` on the host for full host-side details. +If you run `openclaw nemoclaw status` from inside the sandbox, the command detects the sandbox context and reports it. Host-level sandbox and inference details are not available from within the sandbox. Run `openshell sandbox list` on the host to check the underlying sandbox state. ## View Blueprint and Sandbox Logs @@ -108,21 +108,9 @@ If the request fails, check the following: 2. Run `openclaw nemoclaw logs -f` to view error messages from the blueprint runner. 3. Verify that the inference endpoint is reachable from the host. -## Common Issues - -The following table lists common problems and their resolution steps: - -| Symptom | Resolution | -|---|---| -| Sandbox shows as stopped | Run `nemoclaw onboard` to recreate the sandbox. | -| Inference requests time out | Verify the provider endpoint is reachable. Check `openclaw nemoclaw status` for the active endpoint. | -| Agent cannot reach an external host | Open the TUI with `openshell term` and approve the blocked request, or add the endpoint to the policy. | -| Blueprint run failed | Run `openclaw nemoclaw logs --run-id ` to view the error output for the failed run. | -| cgroup v2 error during onboard | On Ubuntu 24.04, DGX Spark, or WSL2, Docker requires `"default-cgroupns-mode": "host"` in `/etc/docker/daemon.json`. Run `nemoclaw setup-spark` to apply this fix, then retry `nemoclaw onboard`. | -| Status shows "not running" inside sandbox | This is expected. The status command cannot query host-level state from within the sandbox. Run `openshell sandbox status` on the host instead. | - ## Related Topics +- [Troubleshooting](../reference/troubleshooting.md) for common issues and resolution steps. - [Commands](../reference/commands.md) for the full CLI reference. - [Approve or Deny Agent Network Requests](../network-policy/approve-network-requests.md) for the operator approval flow. - [Switch Inference Providers](../inference/switch-inference-providers.md) to change the active provider. diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 6d7ef234f11..f023b791bd5 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -63,7 +63,9 @@ $ openclaw nemoclaw status [--json] `--json` : Output as JSON for programmatic consumption. -When you run `status` inside an active OpenShell sandbox, host-level commands like `openshell sandbox status` are unavailable. The status command detects this and reports the sandbox context instead of showing false negatives. Run `openshell sandbox status` on the host for full details. +When running inside an active OpenShell sandbox, the status command detects the sandbox context and reports "active (inside sandbox)" instead of false negatives. +Host-side sandbox state and inference configuration are not inspectable from inside the sandbox. +Run `openshell sandbox list` on the host to check the underlying sandbox state. ### `openclaw nemoclaw logs` @@ -106,13 +108,12 @@ $ nemoclaw onboard The first run prompts for your NVIDIA API key and saves it to `~/.nemoclaw/credentials.json`. -The onboard wizard runs a preflight check before creating the gateway. On systems with cgroup v2, such as Ubuntu 24.04 and DGX Spark, the preflight verifies that Docker is configured with `"default-cgroupns-mode": "host"` in `/etc/docker/daemon.json`. If this setting is missing, `nemoclaw onboard` exits with an error and directs you to run `nemoclaw setup-spark` to apply the fix. +The wizard prompts for a sandbox name. +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. -By default, the onboard menu shows NVIDIA cloud inference options only. To enable experimental local inference options (NIM, vLLM, Ollama), set the `NEMOCLAW_EXPERIMENTAL` environment variable before running onboard: - -```console -$ NEMOCLAW_EXPERIMENTAL=1 nemoclaw onboard -``` +Before creating the gateway, the wizard runs preflight checks. +On systems with cgroup v2 (Ubuntu 24.04, DGX Spark, WSL2), it verifies that Docker is configured with `"default-cgroupns-mode": "host"` and provides fix instructions if the setting is missing. ### `nemoclaw list` @@ -228,3 +229,8 @@ $ nemoclaw status Set up NemoClaw on DGX Spark. This command applies cgroup v2 and Docker fixes required for Ubuntu 24.04. Run with `sudo` on the Spark host. +After the fixes complete, the script prompts you to run `nemoclaw onboard` to continue setup. + +```console +$ sudo nemoclaw setup-spark +``` diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md new file mode 100644 index 00000000000..0bc554baf7d --- /dev/null +++ b/docs/reference/troubleshooting.md @@ -0,0 +1,126 @@ +--- +title: + page: "NemoClaw Troubleshooting Guide" + nav: "Troubleshooting" +description: "Diagnose and resolve common NemoClaw installation, onboarding, and runtime issues." +keywords: ["nemoclaw troubleshooting", "nemoclaw debug sandbox issues"] +topics: ["generative_ai", "ai_agents"] +tags: ["openclaw", "openshell", "troubleshooting", "nemoclaw"] +content: + type: reference + difficulty: technical_beginner + audience: ["developer", "engineer"] +status: published +--- + + + +# Troubleshooting + +This page covers common issues you may encounter when installing, onboarding, or running NemoClaw, along with their resolution steps. + +## 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. + +## 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: + +```console +$ 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: + +```console +$ 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 running `openclaw nemoclaw 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: + +```console +$ openclaw nemoclaw status +``` + +If the endpoint is correct but requests still fail, check for network policy rules that may block the connection, and verify that your NVIDIA API key is valid. + +### 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: + +```console +$ openshell term +``` + +To permanently allow an endpoint, add it to the network policy. +Refer to [Customize the Network Policy](../network-policy/customize-network-policy.md) for details. + +### Blueprint run failed + +View the error output for the failed blueprint run: + +```console +$ openclaw nemoclaw logs --run-id +``` + +If the run ID is unknown, omit `--run-id` to view logs from the most recent run. +Use `--follow` to stream logs in real time while debugging.