--- title: "🦞 Set Up Example NemoClaw Agents 🦞 — Troubleshooting" canonical: "https://build.nvidia.com/spark/nemoclaw-applications/troubleshooting.md" --- # Troubleshooting Tables below are grouped by tab so you can jump straight to the workflow you're debugging. Start with **General sandbox & policy issues** if the failure is at the `nemoclaw` / `openshell` command layer rather than inside a specific application. ## General sandbox & policy issues | Symptom | Cause | Fix | |---------|-------|-----| | `nemoclaw policy-add` returns `unknown sandbox` | Sandbox name typo, or sandbox was deleted | Run `nemoclaw list` to see registered sandboxes; rerun the command with the exact name. If empty, re-run the NemoClaw installer to recreate the sandbox. | | `openshell policy set` fails with `validation failed` / exit code 1 | Malformed YAML or invalid policy fields | Common issues: paths must start with `/`, no `..` traversal, `run_as_user` must not be `root`, `network_policies` entries need both `host` and `port`. Fix the YAML and retry. | | `openshell policy set` fails with `unknown field 'Version', expected one of 'version', 'filesystem_policy', 'landlock', 'process', 'network_policies'` | Round-trip bug in openshell `0.0.44`: `openshell policy get --full` emits the top-level key as `Version:` (capital V), but `openshell policy set` only accepts `version:` (lowercase) | Lowercase the key in place and retry: `sed -i 's/^Version:/version:/' policy.yaml && openshell policy set $SANDBOX_NAME --policy policy.yaml --wait`. Preferred: skip the full-policy round trip entirely and use the additive flow — write a small preset file with `preset:` + `network_policies:` blocks and apply it with `nemoclaw $SANDBOX_NAME policy-add --from-file ./my-preset.yaml --yes`. The additive flow never touches the live `version:` field. | | `openshell policy get` shows your new network rule but the sandbox still blocks the host | Hot-reload did not complete | Re-run with `--wait` so the CLI blocks until the update is confirmed: `openshell policy set $SANDBOX_NAME --policy policy.yaml --wait`. If still failing, restart the sandbox gateway with `nemoclaw $SANDBOX_NAME recover` (restarts the sandbox gateway and dashboard port-forward); if that doesn't clear the symptom, recreate the sandbox. | | Cannot recreate sandbox: `port 8080 is held by container...` | A previous OpenShell gateway or sandbox container still owns port 8080 | `openshell gateway destroy -g ` (or `docker stop && docker rm `), then re-run `nemoclaw onboard`. | | `policy-add` does not list the preset I expected | Preset depends on NemoClaw version | List what your version supports: `nemoclaw $SANDBOX_NAME policy-add --help` or run `policy-add` interactively and read the menu. Newer presets may require updating NemoClaw. | | `nemoclaw policy-add --from-file ...` fails with `Preset must declare preset.name (lowercase, hyphenated RFC 1123 label)` | `preset.name` in your custom preset file contains an underscore, uppercase letter, or other non-RFC-1123 character | Change the value of `preset.name` to lowercase letters, digits, and hyphens only (e.g. `news_sources` → `news-sources`). The inner `network_policies.` map key and its `name` field do accept underscores — the constraint is only on the top-level `preset.name`. | | Web UI shows `origin not allowed` after policy changes | Accessing via `localhost` instead of `127.0.0.1` | Use `http://127.0.0.1:18789/#token=`. The gateway origin check requires `127.0.0.1` exactly. | ## [NemoClaw Policy Setup](https://build.nvidia.com/spark/nemoclaw-applications/policy-setup) | Symptom | Cause | Fix | |---------|-------|-----| | Telegram bot replies `Error: Channel is unavailable: telegram` | Telegram channel plugin was not wired into the sandbox at onboard | `policy-add telegram` alone is not enough. First try the non-destructive fix: run `nemoclaw $SANDBOX_NAME channels add telegram` (you will be prompted for bot token and app token if they are not already in the environment); this wires the channel plugin into the existing sandbox without touching your config, presets, or mounts. If the command is unavailable in your version, fall back to re-running the NemoClaw installer (see the **Download, verify, then execute** snippet in [NemoClaw Policy Setup](https://build.nvidia.com/spark/nemoclaw-applications/policy-setup)) and selecting `telegram` at the **Messaging channels** prompt. | | `nemoclaw tunnel start` prints `cloudflared not found — no public URL` | `cloudflared` is not installed | Reinstall it: `curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm64.deb && sudo dpkg -i cloudflared.deb`, then `nemoclaw tunnel stop && nemoclaw tunnel start`. | | Telegram bot receives messages but returns nothing for 60+ seconds | First response on a 120B model is slow (cold start), or Ollama not warm | Expected for the first reply after a restart. Verify the inference route with `nemoclaw $SANDBOX_NAME status`. If subsequent replies are also slow, pick a smaller model in the NemoClaw onboard wizard. | ## [Daily Personal News Digest](https://build.nvidia.com/spark/nemoclaw-applications/news-digest) | Symptom | Cause | Fix | |---------|-------|-----| | Scheduled digest never fires | The agent did not persist a scheduled task | Ask in the web UI: *"Show me all scheduled tasks."* If empty, re-issue the prompt and explicitly say *"Register this as a recurring scheduled task using your built-in scheduler."* | | Digest fires but message says `unable to fetch ` | Host is not in `network_policies` | Add the host as a new entry under `network_policies.news_sources.endpoints` in `news-sources.yaml` (the preset file from Step 1) and re-run `nemoclaw $SANDBOX_NAME policy-add --from-file ./news-sources.yaml --yes`. Outbound denials show up in `nemoclaw $SANDBOX_NAME logs --follow` and `openshell term`. | | Agent skips the setup questions and dives straight into a generic digest | Profile from a prior run is still in memory | Send *"Forget my profile and run the one-time setup again from scratch."* and re-answer the six questions. | ## [Software Development Agent](https://build.nvidia.com/spark/nemoclaw-applications/developer-agent) | Symptom | Cause | Fix | |---------|-------|-----| | Agent writes `develop-and-review.md` but the host file is missing | Looking at the wrong host path, or the `share mount` is not active | The sandbox path `/sandbox/project` maps to the host directory you passed to `nemoclaw $SANDBOX_NAME share mount` (e.g. `~/nemoclaw-projects/my-app`). Open `develop-and-review.md` under that host directory, not inside `/sandbox/project` on the host. Verify the mount is live with `nemoclaw $SANDBOX_NAME share status`. If it says "not mounted", re-run the `share mount` command from Step 1. | | Agent fails with `Permission denied` when writing `develop-and-review.md` | Host directory was locked with `chmod a-w` and the mount inherits those permissions via SSHFS | Restore write on the host: `chmod u+w ~/nemoclaw-projects/my-app` (or whichever directory you mounted) and retry. For a kernel-enforced write boundary inside the sandbox in addition to host permissions, tighten `filesystem_policy` in the sandbox policy and `nemoclaw $SANDBOX_NAME rebuild` — filesystem policy is locked at sandbox creation, so it requires a rebuild to change (workspace state is preserved automatically). | | Agent runs tests and reports "tests not run" even though the project has tests | Test runner not installed in the sandbox image | The default NemoClaw sandbox may not ship `pytest`, `npm`, `cargo`, or `go test`. Install whatever the project uses once after sandbox creation: `nemoclaw $SANDBOX_NAME connect`, then `pip install --user pytest` (or equivalent), then `exit`. | | Agent modifies files outside the plan | Plan-approval checkpoint was disabled | In the profile, answer `yes` to "pause for approval" (Q5). The agent must then print `PLAN READY — reply 'approve'` and wait, never modifying source files until you reply `approve`. | ## [Deck Reviewer](https://build.nvidia.com/spark/nemoclaw-applications/deck-reviewer) | Symptom | Cause | Fix | |---------|-------|-----| | Agent reports "ingested 0 artifacts" | Queue directory is empty or files match `ignore_paths` | Confirm files exist with `ls ~/nemoclaw-redteam/queue/` on the host. Check `profile.yaml.ignore_paths` for a glob that's catching your files (e.g. `**/~$*` excludes Office lock files). | | Agent reports "parser not available" for `.pptx` or `.pdf` | `python-pptx` / `pdfplumber` not installed in the sandbox | Install once: `nemoclaw $SANDBOX_NAME connect`, then `pip install --user python-pptx python-docx pdfplumber markdown-it-py wcag-contrast-ratio`, then `exit`. The agent falls back to plain-text extraction if a parser is missing — flag it explicitly if you'd rather not install Python packages. | | Same finding keeps re-appearing after I dismissed it | Dismissal mode is `None`, or the rule + location pair did not match | Confirm profile Q4 is `Sticky` or `Per-version`. Check `~/nemoclaw-redteam/memory/dismissals.jsonl` to verify the dismissal was written. If the `location` field differs by a single character (e.g. "Slide 1" vs "slide 1"), the agent treats them as different sites — ask the agent to dismiss again using the exact coordinates from the latest report. | | CRITICAL findings disappear from the report | Auto-dismiss was attempted (should be impossible) | This is a regression — CRITICAL is hardcoded to require `yes, dismiss critical` re-confirmation per the prompt's DISMISSAL PROTOCOL. Re-paste the full prompt to restore the rule and re-run. | ## [Calendar Negotiator](https://build.nvidia.com/spark/nemoclaw-applications/calendar-negotiator) | Symptom | Cause | Fix | |---------|-------|-----| | Agent proposes slots inside my focus blocks | `profile.yaml` not being re-read each run, or approval threshold permits it | The agent is required to re-read `calendar.ics` and `profile.yaml` on every request (workflow step 2 LOAD). Verify the focus block is actually in `profile.yaml` and not just in your head. Tighten profile Q6 (approval threshold) to `Always ask` if the agent's `Ask only if...` carve-out is firing too often. | | Agent shares event titles or attendees from `calendar.ics` with the other party | Information disclosure profile (Q5) set to `slots + reasons` | Reset profile Q5 to `slots only`. The negotiation safety rules also forbid leaking event titles, attendees, or locations — if the agent did so under `slots only`, re-paste the full prompt to restore the rule. | | Booking file overwrites a confirmed prior booking | Agent did not honor the "never overwrite" rule | Check `~/nemoclaw-calendar/bookings/` for a `-v2.md` file — the rule requires a new file with `-v2` suffix when a meeting is moved. If overwritten, restore from your filesystem snapshot or last backup; re-paste the full prompt to restore the rule. | | Agent never DMs the other party even in `proxy` mode | Telegram channel not wired or other party's chat not opened | First, confirm Telegram works for **you** by sending the bot a `hello`. Then confirm the other party has actually opened a chat with the bot at least once (`/start`); Telegram bots cannot DM users who have not initiated contact. | > [!NOTE] > For installer-level NemoClaw issues (Docker, Ollama, gateway, Telegram setup), see the **Troubleshooting** tab of the [NemoClaw on DGX Spark](https://build.nvidia.com/spark/nemoclaw) playbook before debugging here — most reported issues come from the install layer rather than the application layer. --- > [!NOTE] > DGX Spark uses a Unified Memory Architecture (UMA), which enables dynamic memory sharing between the GPU and CPU. With many applications still updating to take advantage of UMA, you may encounter memory issues even when within the memory capacity of DGX Spark. If that happens, manually flush the buffer cache with: ```bash sudo sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches' ``` For the latest known issues, please review the [DGX Spark User Guide](https://docs.nvidia.com/dgx/dgx-spark/known-issues.html).