---
title: "Troubleshooting"
---

# Troubleshooting

Causes and fixes for common problems in the Agents app, from sessions that will not start to refused actions, missing engines, worktrees and the link to the Editor.

Sign-in, policy, audit, model and context problems are the same in both apps; see the Editor's [Troubleshooting](https://neuralinverse.com/docs/editor/troubleshooting/) for their codes. This page covers what is specific to the Agents app. The Agents window has no status bar: the connection and policy state is in the title bar, and the account menu has the server and account details.

## Sessions

| Symptom | Cause | Fix |
|---|---|---|
| "Neural Inverse uses your own models..." and nothing runs | No model is connected | Choose **Connect a Model...**, or open **Manage Models**. See [Models](https://neuralinverse.com/docs/editor/models/). |
| Sessions in a repository are refused | The policy requires an intent and none is set | Set it in the new-session toolbar. See [Intent, projects and releases](https://neuralinverse.com/docs/editor/intent-and-projects/). |
| Agent sessions, tool calls and model calls are all refused; the title bar shows the policy locked | The organisation policy expired beyond its grace, cannot be verified, or was revoked | Your administrator distributes a current policy |
| An engine is blocked for the session | A mandatory rule cannot be enforced by that engine version, or governance does not know the version | The Governance view names the rule; use another engine or ask your administrator |
| Codex is not offered | `chat.agentHost.codexAgent.enabled` is off by default, and Codex needs a ChatGPT or OpenAI Codex account | Sign in to ChatGPT under **Subscriptions** on the Models page and turn the setting on |
| A change to the Claude engine setting has no effect | The agent host has not restarted | Quit both apps; on macOS the shared host stops by itself once idle |
| Sessions stop when the Agents app quits (Windows, Linux) | Each app has its own agent host there | Set `NI_SHARED_AGENT_HOST=1` to try the shared host, which is not yet validated on these platforms |

## Actions refused

| Symptom | Cause | Fix |
|---|---|---|
| An action was refused with a rule and reason | The policy denies it | Change the approach, or ask your administrator about the rule |
| An action needing approval was refused without asking you | Nobody attended the session (for example an automation run) | Run the task in an attended session, or ask for the rule to change |
| You cannot approve an action yourself | An approval rule or a control applies | **Request Approval**, commit `.neuralinverse/records`, and ask enrolled approvers to sign |
| An agent could not edit a hook, CI file, shell profile or policy file | Built-in protection, with or without a policy | Make that change yourself |
| A command was sent for approval although it looks harmless | It could not be analysed (for example `eval`, a program name in a variable, encoded PowerShell) | Approve it if you understand it, or ask the agent to write it plainly |
| The agent's terminal has no credentials | Credentials are withheld from agent terminals by design | Use **Run with Secrets...** in the Editor for your own runs. See [Secrets and agent terminals](https://neuralinverse.com/docs/editor/secrets/). |

## Worktrees and changes

| Symptom | Cause | Fix |
|---|---|---|
| "Failed to apply changes to parent repo. The parent repo may have diverged" | The parent repository moved on since the worktree branched | Resolve the conflicts by hand in the parent repository |
| "Could not determine worktree branch name." | The worktree is not on a branch | Check out a branch in the worktree |
| Compare Models cannot launch | The repository has no commit or no remote, an engine does not support worktrees, or a permission choice is locked | Fix the repository, choose other engines, or change the permission |
| Disk filling with worktrees | Inactive worktrees accumulate | Use **Open Worktree Cleanup**, or move them with `sessions.worktreeLocation` |

## Team work

| Symptom | Fix |
|---|---|
| A session says it is not registered because the repository has no remote | Add a remote |
| "Team work is not turned on for you." | Ask an administrator; nothing is blocked meanwhile |

See [Team work](https://neuralinverse.com/docs/editor/team-work/) for the full list.

## The Editor link

| Symptom | Cause | Fix |
|---|---|---|
| "Neural Inverse could not be opened. It is installed together with this app; reinstall Neural Inverse if it is missing." | The Editor is not installed or could not start | Reinstall Neural Inverse |
| Signed out in the Agents app after signing out of the Editor | The apps keep sign-in in step | Sign in again; the other app offers a one-click sign-in |

## Automations

| Symptom | Cause | Fix |
|---|---|---|
| Automations are unavailable with upgrade guidance | The agent host is older than the client expects | Update Neural Inverse |
| A scheduled run did not start | The agent host was not running, or required credentials are missing | Keep the host running; check models and sign-in |
| A run ended early | It reached `chat.automations.runTimeoutMinutes` | Raise the timeout (pre-release builds) or split the task |