Ready-to-run workflows you can copy and personalize
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.
Set your sandbox name once in this shell. The fixes below use $SANDBOX_NAME:
export SANDBOX_NAME=my-assistant # the name you chose at NemoClaw onboard
| Symptom | Cause | Fix |
|---|---|---|
nemoclaw <sandbox> 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, follow Run NemoClaw with a Local LLM 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' | policy get --full prepends a metadata header (Version:, Hash:, Status:, Source:, Config rev:) and a --- separator that are not part of the policy document | Strip that header, then set: awk 'f{print} /^---$/{f=1}' policy.yaml > policy-clean.yaml followed by openshell policy set $SANDBOX_NAME --policy policy-clean.yaml --wait. Preferred: skip the full-policy round trip entirely and use the additive policy-add --from-file flow, which 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 remove -g <old-gateway-name> (or docker stop <name> && docker rm <name>), then re-run nemoclaw onboard. |
policy-add does not list the preset I expected | Preset name not in the interactive menu for this install | List available presets: nemoclaw $SANDBOX_NAME policy-add --help or run policy-add interactively and read the menu. Update NemoClaw if you need a maintained preset that is not listed. |
nemoclaw <sandbox> 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.<group> 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 | The browser URL does not match the URL printed by dashboard-url | Open the URL exactly as printed by nemoclaw $SANDBOX_NAME dashboard-url --quiet. |
| 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 that command is unavailable, re-run the NemoClaw installer and answer n when it offers Express install — the Messaging channels prompt only appears in the custom onboarding wizard. Pick telegram there to recreate the sandbox with the channel plugin attached. |
nemoclaw tunnel start prints cloudflared not found — no public URL | cloudflared is not installed (affects optional remote Web UI only — Telegram messaging does not need a tunnel) | If you need a public dashboard URL, install cloudflared for your host architecture (on ARM64: 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. Skip this entirely for Telegram-only workflows. |
| Telegram bot receives messages but returns nothing for 60+ seconds | First response after a restart is slow (cold start) while the model loads | 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 (see the companion playbook). |
| 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 <url> | 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. |
| Symptom | Cause | Fix |
|---|---|---|
Agent writes develop-and-review.md but the host file is missing | The report is written inside the sandbox and has not been pulled back to the host | The report is written inside the sandbox at /sandbox/project. Pull it back with the Step 1 command: nemoclaw $SANDBOX_NAME exec -- bash -lc 'cd /sandbox/project && tar czf - .' | tar xzf - -C ~/nemoclaw-projects/my-app, then open develop-and-review.md in that host directory. (If you chose the optional share mount path instead, check it with nemoclaw $SANDBOX_NAME share status.) |
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. |
| 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. |
| 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, local inference, gateway, Telegram setup), see the Troubleshooting tab of Run NemoClaw with a Local LLM before debugging here — most reported issues come from the install layer rather than the application layer.
NOTE
Some hardware platforms use Unified Memory Architecture (UMA), which enables dynamic memory sharing between the GPU and CPU. If you hit memory pressure even when within rated capacity, manually flush the buffer cache with:
sudo sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches'
For latest known issues, see the documentation linked under Resources for your hardware platform.