> This page is for version 3.3.0 (default).
> For other versions, use one of these documentation indexes:
> - 3.3.0 (default): https://docs.nvidia.com/vss/3.3.0/llms.txt
> - Dev: https://docs.nvidia.com/vss/dev/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/vss/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/vss/_mcp/server.

# Troubleshooting

Recovery steps for common NemoClaw / OpenClaw / VSS orchestrator issues. Substitute your sandbox name wherever `<sandbox>` appears. The manual notebook flow in [Deploy VSS and Skills](/vision-agent/agent-harnesses/nemoclaw/setup-vss-and-skills) uses `vss-harness-sandbox` by default. If you override `NEMOCLAW_SANDBOX_NAME`, use the sandbox name printed by the notebook instead.

> **Note**
>
> If the Build Vision AI Skill provisioned NemoClaw, use the sandbox name returned
> by the Skill. Ask your coding agent to resume the Skill for the existing build
> and rerun the harness setup; the Skill executes `deploy_nemoclaw.ipynb`
> non-interactively and recreates an existing sandbox so the selected provider,
> endpoint, model, and credentials are applied. Recreation discards that
> sandbox's agent sessions. Do not manually rerun individual notebook cells for
> this flow. The
> numbered-section recovery steps below apply when you ran the notebook manually.

## Cursor or IDE Kernel Uses Node.js 20

**Symptom**: Section 3.1 of `deploy_nemoclaw.ipynb` fails during the NemoClaw installer with a Node.js version error.

**Cause**: NemoClaw's pinned installer needs Node.js `>= 22.19`. Cursor and some other IDEs can put their bundled Node.js 20 ahead of `nvm` on the Jupyter kernel's `PATH`.

**Solution**: Fix the Node.js version manually in a host terminal, then restart the Jupyter kernel and re-run the failed Section 3.1 cell:

**`Run in the NemoClaw host terminal`**

```bash title="Run in the NemoClaw host terminal"
# Install nvm + Node 22 (skip the curl line if nvm is already installed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
export NVM_DIR="$HOME/.nvm"; . "$NVM_DIR/nvm.sh"
nvm install 22 && nvm alias default 22

# Prepend Node 22 ahead of Cursor's bundled Node 20, then launch Cursor from THIS shell
export PATH="$NVM_DIR/versions/node/$(nvm version 22)/bin:$PATH"
node -v   # must print v22.x
```

Launching Cursor from a terminal where `node -v` reports `v22.x` makes the kernel inherit the correct `PATH`. Alternatively, leave Cursor as-is and run this NemoClaw step from a plain terminal instead of the IDE kernel.

## Agent UI Not Reachable

**Symptom**: The Agent UI link from `deploy_nemoclaw.ipynb` Section 3.5 fails to load, hangs, or times out.

**Cause**: The OpenShell dashboard forward on `18789` stopped, was never created, or points at the wrong sandbox.

**Solution**:

1. Check the local health endpoint:

   **`Run in the NemoClaw host terminal`**

   ```bash title="Run in the NemoClaw host terminal"
   curl -fsS http://127.0.0.1:18789/health
   ```

2. List active forwards:

   **`Run in the NemoClaw host terminal`**

   ```bash title="Run in the NemoClaw host terminal"
   openshell forward list
   ```

   Look for `<sandbox>` on port `18789` with status `running`.

3. Restart the forward:

   **`Run in the NemoClaw host terminal`**

   ```bash title="Run in the NemoClaw host terminal"
   openshell forward stop 18789 <sandbox>
   openshell forward start --background 18789 <sandbox>
   ```

4. If you are not on the Brev instance directly, keep an SSH tunnel open from your laptop:

   **`Run in your local terminal`**

   ```bash title="Run in your local terminal"
   ssh -L 18789:127.0.0.1:18789 <user>@<nemoclaw-host>
   ```

## Dashboard Port Already in Use

**Symptom**: The Build Vision AI Skill stops at harness selection, before deploying, naming what holds `18789` or `18790`. On a manual notebook run the same conflict surfaces later: Section 3.1 onboarding ends with "Port 18789 is not available." if you exported `NEMOCLAW_DASHBOARD_PORT`, or puts the sandbox dashboard on the next free port in `18789`–`18799` if you did not, leaving the rest of the notebook addressing `18789`; Section 3.5 stops with "Port 18790 is held by pid …, which is not '\<sandbox>'s dashboard relay". A NemoClaw older than the pinned `NEMOCLAW_INSTALL_REF` reported the onboarding half as "did not receive the required baseline scopes" instead.

**Cause**: Every sandbox defaults to the same two ports — `NEMOCLAW_DASHBOARD_PORT` (`18789`) and `NEMOCLAW_DASHBOARD_RELAY_PORT` (`18790`) — so any sandbox left running on the host holds them. The notebook reclaims a port only from **its own** sandbox name: Section 3.1 replaces the sandbox named `NEMOCLAW_SANDBOX_NAME` when `NEMOCLAW_RECREATE_SANDBOX` is `True`, and Section 3.5 replaces that name's relay started from the same checkout. Anything else — another sandbox name, a relay from a second clone, or an unrelated listener — is left alone by design.

The auto-allocation range (`18789`–`18799`) includes the relay's own default, so an onboard that reallocates because `18789` is taken can hand the sandbox dashboard `18790` and leave Section 3.5 with nowhere to bind. Export both `NEMOCLAW_DASHBOARD_PORT` and `NEMOCLAW_DASHBOARD_RELAY_PORT` to keep the two apart: that also makes the dashboard port explicit, so onboard reports a conflict instead of moving the sandbox, and the notebook's equality check only catches values you set yourself.

**Limitation**: Neither the notebook nor teardown cleans up a sandbox it does not own. Teardown also leaves the relay and watchdog of any sandbox it did not destroy.

**Solution**: Identify the owner, then clear it yourself — neither the Skill nor the notebook will destroy a sandbox it does not own:

**`Run in the NemoClaw host terminal`**

```bash title="Run in the NemoClaw host terminal"
# Absent until notebook Section 3.1 installs it, so do not let it fail the probe.
command -v openshell >/dev/null \
  && openshell sandbox list                         # compare against NEMOCLAW_SANDBOX_NAME
for port in "${NEMOCLAW_DASHBOARD_PORT:-18789}" "${NEMOCLAW_DASHBOARD_RELAY_PORT:-18790}"; do
  python3 -c 'import socket,sys; s=socket.socket(); s.setsockopt(socket.SOL_SOCKET,socket.SO_REUSEADDR,1); s.bind(("",int(sys.argv[1])))' "$port" 2>/dev/null \
    && { echo "$port free"; continue; }
  # The holder's own command line is what names its sandbox: the forward is an
  # `openshell ... forward service <name>` process, so no --sandbox pattern
  # finds it, and the PID alone says nothing about ownership.
  echo "$port held by:"
  for pid in $(lsof -tnP -iTCP:"$port" -sTCP:LISTEN 2>/dev/null \
    || ss -Hltnp "sport = :$port" 2>/dev/null | grep -o 'pid=[0-9]*' | cut -d= -f2); do
    printf '  %s: ' "$pid"; tr '\0' ' ' 2>/dev/null <"/proc/$pid/cmdline"; echo
  done
done
# stderr first: a process that exits mid-scan makes the shell's own open fail.
# `--sandbox` is required, not decoration: the echo below carries the relay path
# in this block's own command line, which `[d]` does not hide from the scan.
for f in /proc/[0-9]*/cmdline; do tr '\0' ' ' 2>/dev/null <"$f"; echo; done \
  | grep -E '[d]ashboard-(relay|forward-watchdog)\.py .*--sandbox '  # names the owner
# A relay must carry this path to count as yours, not just the sandbox name.
# The notebook's own value, from any directory you run this in.
HARNESS_SRC="$(cd "${VSS_REPO_DIR:-$HOME/video-search-and-summarization}" && pwd -P)"  # harness source ref: <that>/_builds/<name>/harness-src
echo "your relay: $HARNESS_SRC/deploy/docker/scripts/nemoclaw/dashboard-relay.py"
```

The bind test decides free or held on its own, so a host without `lsof` or `ss`
still sees the conflict — it just cannot name the holder. Probe the ports your
deployment actually uses: the loop reads `NEMOCLAW_DASHBOARD_PORT` and
`NEMOCLAW_DASHBOARD_RELAY_PORT` when you have overridden either default.

A matching sandbox name is not enough for the relay: Section 3.5 keeps one only
when its script path is the one under `VSS_REPO_DIR` too, so a same-name relay
from a second clone is foreign and must be stopped like any other. If you
deployed from a harness source ref, that path is the `_builds/<name>/harness-src`
worktree rather than the checkout — compare against the worktree, or the
checkout's own relay will look like yours when Section 3.5 will reject it. With
`VSS_REPO_DIR` unset the notebook uses `$HOME/video-search-and-summarization`,
so export it when your checkout lives elsewhere.

**`Run in the NemoClaw host terminal`**

```bash title="Run in the NemoClaw host terminal"
# Watchdog first: it answers a dying forward with `nemoclaw recover`. Relay
# last: `destroy` releases the forward, never the relay. Drop the `destroy`
# when `openshell sandbox list` no longer shows <other>.
OTHER='<other>'
# pkill -f compiles an extended regex, so escape every metacharacter in the
# name: an unescaped one matches other sandboxes' processes too, and these
# scripts are shared by every sandbox on the host.
OTHER_RE="$(printf '%s' "$OTHER" | sed 's/[][(){}.*+?^$|\\]/\\&/g')"
pkill -f -- "dashboard-forward-watchdog\.py --sandbox ${OTHER_RE}( |$)"
nemoclaw "$OTHER" destroy --yes --cleanup-gateway
pkill -f -- "dashboard-relay\.py --sandbox ${OTHER_RE}( |$)"
```

Each port must be free, or held by your own sandbox name — which Section 3.1 reclaims with `NEMOCLAW_RECREATE_SANDBOX` — before you continue. Then ask your coding agent to resume the Skill, or re-run Section 3 after a manual notebook run.

## MCP Tools Not Visible or Not Reachable

**Symptom**: The agent cannot list `vss_orchestrator__*` tools, tool calls time out, or the Section 5 Agent UI verification cannot reach the MCP server.

**Solution**: Run the following checks on the VSS host that runs the orchestrator MCP server:

1. Re-run `deploy_vss_orchestrator.ipynb` Section 4. It stops any previously recorded `VSS_ORCHESTRATOR_MCP_PID`, starts the MCP server on `9988`, and polls health.

2. Check the MCP log:

   **`Run in the VSS host terminal`**

   ```bash title="Run in the VSS host terminal"
   tail -n 100 ~/video-search-and-summarization/.orchestrator-artifacts/vss_orchestrator_mcp.log
   ```

3. From `services/agent/` on the VSS host, call the health tool directly:

   **`Run in the VSS host terminal`**

   ```bash title="Run in the VSS host terminal"
   uv run nat mcp client tool call vss_orchestrator__profiles \
     --url http://127.0.0.1:9988/mcp \
     --transport streamable-http
   ```

4. If the server fails before health, verify `deploy/docker/scripts/vss_orchestrator_mcp_config.yml` paths are valid and writable, especially `mdx_data_dir` and `output_dir`.

5. If NemoClaw and VSS run on separate hosts, verify that the MCP URL registered in the sandbox uses a hostname or IP address that the NemoClaw host can reach. `0.0.0.0` is a server bind address, and `127.0.0.1` reaches only the local host.

## Agent Model or Provider Misconfigured

**Symptom**: Chat fails, `what model are you using?` reports the wrong model, or Section 3.1 of `deploy_nemoclaw.ipynb` errors during `nemoclaw onboard`.

**Solution**:

* If the UI opens but chat fails, re-check the provider setup and active policy.
* If you reproduce the failure from a terminal, use `nemoclaw sandbox exec <sandbox> -- <command>` rather than `docker exec` so the command runs through the documented NemoClaw path with workspace plugins and gateway routing.
* For build.nvidia.com, clear `NEMOCLAW_ENDPOINT_URL` and set `NVIDIA_API_KEY`. `NEMOCLAW_MODEL` can be blank to use `nvidia/nemotron-3-super-120b-a12b`.
* For a custom provider, set all three values: `NEMOCLAW_ENDPOINT_URL`, `NEMOCLAW_MODEL`, and `COMPATIBLE_API_KEY`.
* For a local provider, bind the server to `0.0.0.0` or another non-loopback host address. From inside the sandbox, use `host.openshell.internal` rather than host `127.0.0.1`.
* Re-run the selected Section 1.2 provider cell, then Section 1.3 and Section 3 of `deploy_nemoclaw.ipynb`.

If the sandbox still keeps stale provider state, destroy and recreate it:

**`Run in the NemoClaw host terminal`**

```bash title="Run in the NemoClaw host terminal"
nemoclaw <sandbox> destroy
nemoclaw gc
```

Then re-run Section 3 of `deploy_nemoclaw.ipynb`.

## VSS Skills Missing

**Symptom**: `list your available skills` does not show VSS skills, the Skills tab is empty, or Section 3.6 reports no non-bundled skills.

**Solution**:

The following diagnostic commands apply to OpenClaw. If you onboarded Hermes or another agent harness, run the equivalent checks for that harness.

1. Run `deploy_nemoclaw.ipynb` Section 3.6 to inspect `openclaw plugins doctor` and `openclaw skills list --json`.

2. Check skills from the host:

   **`Run in the NemoClaw host terminal`**

   ```bash title="Run in the NemoClaw host terminal"
   openshell sandbox exec -n <sandbox> -- sh -lc 'openclaw skills list --json'
   ```

3. Confirm the VSS checkout includes the `skills/` directory and the agent harness directory for the selected harness, `.openclaw/` or `.hermes/` (each with its `Dockerfile`).

4. The skills and workspace docs are baked into the sandbox image (`.<harness>/Dockerfile`); re-run Section 3.1 with `NEMOCLAW_RECREATE_SANDBOX` set to rebuild it. In an OpenClaw sandbox, `vss-openclaw-sync` re-selects the active skills from `vss configure check`; in a Hermes sandbox, `vss-hermes-sync` does the same.

## NGC or Model Artifact Downloads Fail

**Symptom**: The perception container (`vss-rtvi-cv`) fails during `ds-start.sh` phase 0, NGC CLI commands fail, or `docker login nvcr.io` fails.

**Solution**:

* Verify `NGC_CLI_API_KEY` is set in `deploy_vss_orchestrator.ipynb` Section 1.1. It is passed through to the perception container, which downloads the models listed in the profile's `models-download.json`.
* Re-run Section 3.1 of `deploy_vss_orchestrator.ipynb` on the host to redo `docker login nvcr.io`. The host needs no NGC CLI and no `~/.ngc/config` — the perception container bootstraps its own and reads the key from the environment.
* Check that `mdx_data_dir` in `deploy/docker/scripts/vss_orchestrator_mcp_config.yml` is writable. Model artifacts are written under `<mdx_data_dir>/models`.

## Compose Operation Stuck or Retried

**Symptom**: A deployment appears stuck, repeated deploy prompts fail with "operation already running", or teardown is needed after a failed `docker_up`.

**Solution**:

* Poll status with the `docker_status` tool using the `docker_compose_ops_id` returned by `docker_up` or `docker_down`.
* Ask the agent to fetch logs with `docker_logs` for the failing container.
* To stop a running deployment, ask the agent to tear it down. `docker_down` can preempt a running `docker_up` for the same `docker_compose_id`.
* Use `deep_clean=true` on `docker_down` only when you intentionally want to delete the configured `mdx_data_dir` after a successful teardown.

## Sandbox or Gateway in a Bad State

**Symptom**: `nemoclaw` or `openshell` commands hang or error out, the agent stops responding, the OpenShell gateway container is missing or unhealthy, or VSS skills fail to load after repeated reinstall attempts.

**Solution**: Destroy the sandbox, garbage-collect leftover state, then recreate it from the notebook.

**`Run in the NemoClaw host terminal`**

```bash title="Run in the NemoClaw host terminal"
nemoclaw <sandbox> destroy
nemoclaw gc
```

Then re-run Section 3 of `deploy_nemoclaw.ipynb`. This recreates the sandbox
from the harness image that contains the VSS skills and workspace docs, then
reapplies the VSS policy and deployment origin. It also configures optional
webhooks and, when HTTPS is enabled, registers the orchestrator MCP path. Run
Section 3.5 to generate a fresh Agent UI link.

## Clean Reinstall

**Symptom**: Destroying the sandbox and restarting the forward does not restore a working environment.

**Solution**: Completely uninstall NemoClaw and OpenClaw, then reinstall from the notebook.

1. Run the bundled NemoClaw uninstaller from the source checkout created by the installer:

   **`Run in the NemoClaw host terminal`**

   ```bash title="Run in the NemoClaw host terminal"
   bash ~/.nemoclaw/source/uninstall.sh
   ```

   The uninstaller removes:

   * All OpenShell sandboxes and the NemoClaw gateway/providers.
   * NemoClaw helper services.
   * NemoClaw / OpenShell / OpenClaw Docker images created during onboarding.
   * `~/.nemoclaw` and `~/.config/{openshell,nemoclaw}` state.
   * The global `nemoclaw` npm install/link and the `openshell` binary.

   Docker, Node.js, npm, and Ollama are preserved.

2. Reinstall by re-running Section 3 of `deploy_nemoclaw.ipynb`. Section 3
   fetches the pinned `NEMOCLAW_INSTALL_REF`, recreates the sandbox from the
   harness image, and reapplies the VSS policy and deployment origin.