---
title: "Troubleshooting"
---

# Troubleshooting

Diagnose common CLI problems with installation, providers, sign-in, policy, permissions, the sandbox, MCP servers, checks, the terminal and networks.

## Start with doctor

```bash
neuralinverse doctor
```

`doctor` (also `/doctor`) checks the Node.js version, platform, terminal, configuration folder and source, model, permission mode, git, ripgrep, the sandbox, MCP servers, proxy settings and, when you use Govern, the sign-in state. Then use these to see what is in effect:

| Command | Shows |
|---|---|
| `neuralinverse config show` | The merged settings, with secrets masked |
| `neuralinverse config path` | The settings files in use |
| `neuralinverse config validate` | Errors in settings files, and keys locked by a managed policy |
| `/env` | Provider variables (set or not), proxy, sandbox, shell, tools on `PATH` |
| `/info` | Session, model and connection overview |
| `--debug` | Diagnostic details on errors |
| `--verbose` | Progress on standard error with `-p`; diagnostics for `acp` and `host` |

## Installation

| Symptom | What to do |
|---|---|
| `doctor` reports the Node.js version as failed | The npm package needs Node.js 22.19 or newer. Upgrade Node.js, or install the [standalone binary](https://neuralinverse.com/docs/cli/install/#install-the-standalone-binary) |
| The install script stops with a checksum error | The downloaded binary did not match the release's `SHA256SUMS`, or the file has no entry. Nothing was installed. Check your mirror (`NI_DOWNLOAD_BASE`) or download again |
| musl-based Linux on arm64 | Only x64 is built for musl. Install with npm |
| `/update` says it does not manage this copy | It updates only npm global installs and binaries in `~/.neuralinverse/bin` (or `NI_INSTALL_DIR`). Update with the tool you installed it with |
| Checks coverage reports an engine error in a standalone binary | The tree-sitter WASM files are missing. Put them in `tree-sitter-wasm/` next to the executable or set `NEURALINVERSE_TREE_SITTER_WASM` |

## Providers and models

| Symptom | What to do |
|---|---|
| The CLI starts setup instead of a session | No usable provider was found. Finish setup, or set a provider variable such as `ANTHROPIC_API_KEY` |
| `-p` exits with an error naming variables | Non-interactive runs do not start setup. Set one of the named variables, or configure a provider first |
| A key is rejected | Run `/provider test` to repeat the live check. Setup stores keys in the keychain; on Linux without a Secret Service session they go to `~/.neuralinverse/credentials.json` |
| A model is refused with "not allowed by your organization's policy" | Your organisation's policy limits models. Pick one from `/model` |
| The model cell shows `▲ model · reconnecting` | A model request failed and is being retried. Press `r` to retry now, `m` to switch model, `l` for the error log |
| Costs look wrong | Costs are estimates from list prices; override `pricing` per model. Your provider's bill is authoritative |
| Requests fail behind a corporate proxy | Set `HTTPS_PROXY` (and `NO_PROXY`), and add your root certificate with `NODE_EXTRA_CA_CERTS` |

## Signing in to Govern

| Symptom | What to do |
|---|---|
| `invalid_client` at sign-in | The Govern server is older than the per-app clients. The administrator upgrades Govern, or sets `keystone.clientId` in managed settings |
| `--issuer is retired: use --base-url <url>` | Use `neuralinverse login --base-url <url>`, or set `keystone.baseUrl` |
| `--base-url cannot change it` | Your organisation's managed settings fix the Govern address |
| Discovery is refused | An answer was not https, redirected, was not the expected JSON, or named a host outside the base URL's domain. Check `keystone.baseUrl` |
| The browser sign-in never completes over SSH | The browser must reach the CLI machine's loopback address. Open the URL on that machine, forward the port, or use `neuralinverse login --device` |
| `Keystone session expired, run neuralinverse login` | Govern refused the token refresh. Sign in again |
| Tokens are kept only in memory | No credential store works on this machine (for example no Secret Service). Sign in again in each process, or set up a Secret Service |
| Signed out unexpectedly | Your device was blocked, revoked or over the device limit (the CLI says which), or you signed out of the Editor or the Agents app, which signs the CLI out at its next start |
| `neuralinverse policy` shows no organisation policy | The current Govern server does not serve the policy route yet; see [Sign in to Govern](https://neuralinverse.com/docs/cli/sign-in/#known-gaps) |
| Model calls and tools are refused; the policy is "locked" | The cached organisation policy is past its offline grace or expired, or keys are pinned and no valid policy could be fetched. Run `/policy refresh` when Govern is reachable |

## Permissions

| Symptom | What to do |
|---|---|
| Everything is denied with `-p` | Nobody can answer in a non-interactive run, so anything that would ask is denied. Grant what the task needs with `--mode` and `--allow` |
| A call is refused in every mode | A deny rule, organisation governance, or a blocking checks finding refused it. `/rules` lists the rules and marks organisation rules |
| You are asked even in `full-auto` | Organisation governance asks for an approval, an ask rule matched, a signed control needs approval, or the tool always asks (such as `fw_flash`) |
| Headless runs are refused for a missing work item | The governance policy requires an intent. Pass `--intent <ref>` |
| `full-auto` is not offered | Administrators set `permissions.disableFullAuto` |
| The agent cannot write `.neuralinverse/settings.json`, `.git/` or shell profiles | These always ask unless an explicit allow rule covers them |
| A shell deny rule did not stop something | Shell deny rules are a guard rail, not a security boundary. Use the sandbox for untrusted work |

## Sandbox

| Symptom | What to do |
|---|---|
| A warning says commands run unsandboxed | The sandbox is enabled but unavailable. Install bubblewrap on Linux; macOS uses the built-in `sandbox-exec`. Set `sandbox.required` to refuse commands instead |
| A command needs network access in the sandbox | Set `sandbox.allowNetwork`, or run it outside the sandbox |
| A command cannot write a file | Only the workspace, the temporary folder and `sandbox.writablePaths` are writable |
| The sandbox fails inside a container | bubblewrap needs user namespaces; on some hosts that means `--security-opt seccomp=unconfined` |

## MCP servers

| Symptom | What to do |
|---|---|
| A server shows as failed | `/mcp` shows its status and logs; `/mcp reconnect <name>` retries. A failing server never blocks the session |
| Slow servers time out | Raise `NEURALINVERSE_MCP_TIMEOUT` (connect, default 30 seconds) or `NEURALINVERSE_MCP_TOOL_TIMEOUT` (calls, default 10 minutes) |
| A server needs sign-in | `neuralinverse mcp login <name>` |
| Every MCP tool asks | Only tools that declare `readOnlyHint` count as read-only. Add an allow rule such as `mcp_github_*` |

## Checks

| Symptom | What to do |
|---|---|
| Findings never block | Only signed rule packs and managed `checks.block` thresholds for signed external findings can block; the baseline pack is advisory |
| A key in the project's settings is ignored | Some `checks` keys are managed only; a warning names them |
| An engine timeout | Raise `checks.budgetMs.agent` or `.commit`. With `checks.failClosed` a timeout of a signed analyser blocks |
| An existing pre-commit hook | `checks hook install` keeps it and chains to it; `--force` replaces it with a backup |

## Terminal

| Symptom | What to do |
|---|---|
| `Shift+Enter` sends instead of starting a new line | Run `/terminal-setup`, or use `Alt+Enter`, `Ctrl+J`, or `\` then `Enter` |
| Colours look wrong | Try `"ui": { "theme": "high-contrast" }` or `"mono"`; `NO_COLOR` and `FORCE_COLOR` are honoured |
| Animation is distracting | `"ui": { "reducedMotion": true }` or `NO_MOTION=1` |
| You prefer a full-screen interface | Use `--fullscreen`, or set `"ui": { "layout": "fullscreen" }` |

## Organisation context

| Symptom | What to do |
|---|---|
| Exit code 5 | You are not signed in, or the session ended. `neuralinverse login` |
| Exit code 6 | Your organisation refused it, the repository is forbidden by the binding policy, or the feature is off for you |
| Exit code 4 | The decision needs a person on a terminal; it cannot be made from a script or an agent's shell |
| The folder is not bound | `neuralinverse context status` says why. Only `origin`, or the branch's tracked remote, is used |

## Firmware and HDL

| Symptom | What to do |
|---|---|
| `/environment` says the setting is ignored | The folder is not a project folder, or the setting was in user-level settings |
| The firmware tools ask before running read-only actions | The project's own files set tool paths or arguments; the CLI asks because a cloned repository could point them anywhere |
| Flashing is denied in CI | Non-interactive runs cannot flash. Flashing always needs a person |
| A probe cannot be reached | Check cables, USB permissions (udev rules on Linux) and power; `fw_toolchain` lists each tool with its version or an install hint |

## Report a problem

`/feedback` writes a bug report or feedback file to attach to an issue; nothing is sent. Report security problems privately to security@neuralinverse.com, with the version (`neuralinverse --version`) and your platform.