Troubleshooting

Startup is slow

The interactive editor accepts drafts while skills, credentials, and model metadata load in workers. /login and other built-in controls work during indexing. Model requests and skill commands queue until their dependencies are ready. Existing skill metadata stays available during refresh; no skill pack needs to be removed to make the editor responsive.

Account writes and summaries also run on workers. A blocked credential refresh does not freeze key entry, logout, model selection or quitting. Use /skills refresh for nested external additions instead of waiting for reconciliation. Updated skill folder aliases retain older slash names.

To identify a remaining delay, launch with NUR_STARTUP_TRACE=1. On PowerShell:

$env:NUR_STARTUP_TRACE = '1'
nur
Remove-Item Env:NUR_STARTUP_TRACE

Read ~/.nur/cache/startup-<pid>.jsonl (or the corresponding NUR_HOME). Compare first_frame, credentials_ready, skills_ready, session_saved, and ready. Root-walk and metadata-index stages distinguish filesystem work from provider waits. These files contain timing data, not prompts or tokens. Automatic updates and ecosystem repair start after preparation reaches an idle point. Fresh-install bootstrap and resumed-history replay retain their existing behavior.

nur doctor

The built-in health check for install, auth, config, and ecosystem:

nur doctor

The check is read-only. It reports the last recorded ecosystem state without running npm, uv, or any other installer. Use nur ecosystem ensure --force to repair or upgrade ecosystem components.

What it checks

Check	Shows
binary	Path to the nur binary
config	Model, effort, max_turns, budget ($/tok caps), config path
auth	Whether a key is set (last 4 chars only)
home	Data home directory
status	Path to status.json
usage	Path to usage.jsonl
sessions	Path to sessions directory
ecosystem	Graphify, PLUR, Ruflo (and related packs) readiness
typesafe	TypeSafe (Jev) layer: ready on a local engine with no key, or inactive
shell	Bash / PowerShell backend
rg, sgrep, git, node, npm, uv, ffmpeg	Whether on PATH (sgrep also looks in ~/.cargo/bin)
vision	look + extract_frames support
sha256	Binary integrity check

Common doctor output

All green:

nur doctor · v0.52.2

binary  C:\Users\you\.local\bin\nur.exe
config  model=muse-spark-1.3 effort=high max_turns=∞ budget=∞$/∞tok  (C:\Users\you\.nur\config.toml)
auth    key set (…abcd)
typesafe Jev judgments active on this machine (local engine · http://127.0.0.1:8788 · no key needed)
home    C:\Users\you\.nur
status  C:\Users\you\.nur\status.json
usage   C:\Users\you\.nur\usage.jsonl
sessions C:\Users\you\.nur\sessions

ecosystem
  graphify  ✓
  plur      ✓
  ruflo     ✓

shell   Git Bash
rg      C:\Program Files\Git\usr\bin\rg.exe
sgrep   C:\Users\you\.cargo\bin\sgrep.exe
git     C:\Program Files\Git\bin\git.exe
node    C:\Program Files\nodejs\node.exe
npm     C:\Program Files\nodejs\npm.cmd
uv      C:\Users\you\.local\bin\uv.exe
ffmpeg  C:\Program Files\ffmpeg\bin\ffmpeg.exe
vision  look · extract_frames (input_image / input_video)

sha256  abc123...  (matches install record)

doctor complete

---

How do I update NurCLI?

nur update

That pulls your Laboratory checkout (~/laboratory/nur-cli or ~/Laboratory/nur-cli), runs cargo build --release, reinstalls ~/.local/bin/nur, and re-runs ecosystem / browser setup.

If…	Then…
No source checkout	nur update falls back to nur install (repair from the running binary)
You use the Windows EXE only	Re-download nur-windows-x86_64.exe from Releases and double‑click, or npx nur-cli, or nur update if you later have a clone
You want a full network reinstall	Re-run npx nur-cli or the one-liner
You only want stack packs refreshed	nur ecosystem ensure --force (does not rebuild the CLI)

Confirm:

nur --version
nur doctor

More: Setup → Update · Commands → nur update.

---

Common issues

command not found: nur

The nur binary is not on your PATH.

Fix:

1. Check where it was installed: ls ~/.local/bin/nur
2. Add ~/.local/bin to your PATH:

   # Bash / Zsh
   export PATH="$HOME/.local/bin:$PATH"
   
   # PowerShell
   $env:Path += ";$env:USERPROFILE\.local\bin"
   

3. Restart your terminal

auth not set

No API key found.

Fix:

nur auth login
# or
export NUR_API_KEY="your-key-here"
# Meta Model API accepts META_API_KEY

droid not found with the Factory provider

Factory chat runs through the droid CLI, so a FACTORY_API_KEY alone is not enough: the launcher has to be on disk. Nur probes ~/.factory/bin, ~/.local/bin, ~/bin, %LOCALAPPDATA%\Programs\factory, /usr/local/bin, /opt/factory/bin and PATH.

Fix: install it (curl -fsSL https://app.factory.ai/cli | sh or npm i -g @factory/cli) and sign in once with droid. If it lives somewhere else, point nur at it:

export NUR_DROID_BIN=/path/to/droid

The message says "signed in, launcher missing" when a Factory session exists but the binary could not be found, so you know which half to fix.

Missing session in /sessions

Sessions are never auto-deleted. If a chat “vanished”:

1. Toggle the sessions picker scope to all (not only this cwd) — Tab or the scope chip.
2. CLI: nur sessions --limit 50 and look at the COST column for high-spend chats.
3. Resume by id: nur -r <prefix> (first 8 chars of the UUID are enough when unique).
4. Check ~/.nur/sessions/. Sidecar *.json.bak may hold the previous save.

Session budget stopped the agent

session cost $X ≥ budget $Y

Fix:

/budget cost 10
/budget clear
/budget save

Or edit max_session_cost_usd / max_session_tokens in ~/.nur/config.toml.

Only an explicit budget can stop a turn. Lines like request preflight: ... - compacting before sending or provider rejected the context window - compacting and retrying are recovery statuses, not failures: Nur shrinks context (larger sibling model, model compaction, local minimal trim) and keeps the turn alive. If a turn truly dies, check ~/.nur/nur.log for the underlying API error.

Garbled text in the TUI on launch

Logs go to ~/.nur/nur.log (not stderr). If you still see noise, check that you're on a current build (nur update) and no wrapper is redirecting RUST_LOG to the console at warn for syntect.

Ecosystem components missing

ecosystem
  graphify  ✗
  plur      ✗
  ruflo     ✗

Fix:

1. Install Node.js 20+ and uv:

   # Windows
   winget install OpenJS.NodeJS.LTS
   winget install astral-sh.uv
   
   # macOS
   brew install node uv
   
   # Linux
   sudo apt install nodejs npm
   pip install uv
   

2. Re-run any one-shot installer:

   nur install
   # or: nur ecosystem ensure --force
   # or re-run npx nur-cli / the one-liner / double-click a fresh release EXE
   

ffmpeg not on PATH

extract_frames requires ffmpeg.

Fix: Install ffmpeg (see Vision).

[sgrep not installed - searched with grep instead …]

The sgrep tool fell back to ripgrep because the Context.dev sgrep binary was not found (nur doctor shows sgrep not found). Results are still correct, just lexical.

Fix: nur ecosystem ensure builds it when cargo is installed (Rust 1.90+; the build takes a few minutes and is retried at most once a week), or run cargo install --git https://github.com/context-dot-dev/sgrep --locked yourself. The first query downloads a 32 MB model into the Hugging Face cache (~/.cache/huggingface/hub; HF_HOME / HF_HUB_CACHE override) - ensure warms it ahead of time. NUR_SGREP_BIN=<path> points at a binary elsewhere; set it empty to turn the tool into plain grep on purpose. sgrep needs rg too; nur passes its own ripgrep location through when PATH does not have one.

sha256 mismatch

Binary may be corrupted or from a different source.

Fix: Re-run a one-shot install:

# already on PATH
nur install

# every OS - prebuilt binary via npm shim
npx nur-cli

# Windows one-liner
irm https://raw.githubusercontent.com/nuroctane/nur-cli/main/install.ps1 | iex

# macOS / Linux one-liner
curl -fsSL https://raw.githubusercontent.com/nuroctane/nur-cli/main/install.sh | bash

# or download nur-windows-x86_64.exe from Releases and double-click

API errors / rate limits

If you see API errors:

1. Check your key: nur auth status
2. Check the model: cat ~/.nur/config.toml
3. Verify the API is up: dev.meta.ai

API error (mid-stream): …

mid-stream is not an HTTP status. It means the request returned 200 and the provider then reported a failure inside the response stream, so there is no status code to show.

The common case is capacity. Providers that queue per worker — NVIDIA NIM, vLLM, Triton, local servers — refuse admission this way:

API error (mid-stream): ResourceExhausted: Worker local total request limit reached (90/32)

nur treats that as a pause, not a failure: it waits and re-offers the turn to the same provider up to three times (1s → 2s → 4s), showing

nvidia is at capacity — waiting 2s, retry 1/3

Retrying only happens when the stream produced no output yet — replaying a turn that already wrote text would duplicate it. If the retries are used up, the normal failover chain takes over.

Billing exhaustion (insufficient_quota, credit balance too low) is not retried — waiting cannot fix it — but it does fail over to another provider.

If you hit this constantly on one provider, you are probably outrunning it: subagents fan out up to 4 at a time, so a small worker pool saturates fast. Send less in parallel, or add a fallback with /failover.

Session not resuming

nur sessions              # list sessions
nur -r <session-id>        # resume by id
nur -c                     # continue most recent for this cwd

config validation errors

config  reasoning_effort is empty — use one of minimal|low|medium|high|xhigh|max|ultracode (or any level your provider accepts)

Fix: Edit ~/.nur/config.toml and set an effort level, or run /effort high. Only an empty value is an error: an unrecognised name is forwarded to the provider as-is, and bare /effort shows what the active route receives.

---

Getting more help

• Run nur doctor for a full diagnostic
• Check the GitHub issues
• Open a new issue with your nur doctor output