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 uses vss-harness-sandbox by default. If you override NEMOCLAW_SANDBOX_NAME, use the sandbox name printed by the notebook instead.

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:

# 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:

   curl -fsS http://127.0.0.1:18789/health

2. List active forwards:

   openshell forward list

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

3. Restart the forward:

   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:

   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:

# 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.

# 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:

   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:

   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:

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:

   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.

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:

   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.