# Troubleshooting

> Find your problem by what you see, and fix it: agents that never show as waiting, an app that won't open, agents stopped after an upgrade, and more.

Source: https://hivemind.griiken.com/guide/troubleshooting/

Find what you see in the table, then follow its fix. Each fix says how to check it worked.

<AgentPrompt description="Paste this into your coding agent, with what you see, to diagnose a Hivemind problem step by step." page="troubleshooting">{`
Hivemind problem: <describe what I see>. Diagnose it on this computer.

1. Gather facts without changing anything: \`hive --version\`; \`hive ctl agents --json; echo "exit $?"\` (exit 3 means neither the app nor \`hive host\` runs); \`hive agents list\` (each agent, on or off, and why any failed to load); \`hive daemon status\`; for a machine, \`hive machine check <name>\`; for other devices, \`hive network show\` and \`hive network doctor\`.
2. Read the logs listed on the Logs and bug reports page for this operating system.
3. Match what you found to a symptom on this page. Quote the exact error text you matched.
4. Tell me the fix before you apply it, and run it only after I say yes. Then run the same check again to show it is fixed.

Anything only I can do (a sudo, a password, accepting an ssh host key, a setting in the app): tell me exactly what to type or press, and wait. Never type a password.
`}</AgentPrompt>

## Start here [#start-here]

1. Check your version: `hive --version`. Then check the [changelog](https://hivemind.griiken.com/guide/changelog/): a newer release may fix it.
2. Look at the logs. [Logs and bug reports](https://hivemind.griiken.com/guide/logs-and-bug-reports/) says where they are on each system.
3. Read the exit code of the `hive` command that failed. The table is in the [CLI reference](https://hivemind.griiken.com/guide/cli/#exit-codes).
4. Still stuck? [Report a bug](https://hivemind.griiken.com/guide/logs-and-bug-reports/#report-a-bug) with what you found.

## Find your problem [#find-your-problem]

| What you see | Go to |
|---|---|
| An agent works, but its tile never turns amber when it asks something | [An agent never shows as waiting](#an-agent-never-shows-as-waiting) |
| `hivemind is damaged and can't be opened` on a Mac | [The app does not open on macOS](#the-app-does-not-open-on-macos) |
| The AppImage closes at once, or prints `SUID sandbox helper` | [The AppImage does not start](#the-appimage-does-not-start) |
| Agents gone, or terminals empty, after an update or a restart | [Agents stopped after an upgrade](#agents-stopped-after-an-upgrade) |
| `hivemind app not running (no socket at …)`, exit 3 | [hive ctl says the app is not running](#hive-ctl-says-the-app-is-not-running) |
| No agent to start, or an agent missing from the menus | [No agent to start](#no-agent-to-start) |
| `no .hivemind/ found` | [Issue commands fail](#issue-commands-fail) |
| A machine shows **Sign in**, or will not connect | [A machine will not connect](#a-machine-will-not-connect) |
| `FORBIDDEN` or `BAD_REQUEST` from a program | [A token is refused](#a-token-is-refused) |
| Your phone or another network cannot reach this computer | [Set up your own network server](https://hivemind.griiken.com/guide/self-hosting/) |

## An agent never shows as waiting [#an-agent-never-shows-as-waiting]

**Why:** Hivemind learns an agent is waiting on you from what the agent tells it, and from reading its screen otherwise. An old copy of the agent, or an agent that has not trusted Hivemind's hooks, tells it nothing.

**Fix:**

1. To see what Hivemind thinks, run `hive ctl agents --json`. Look at the agent's state and its `waiting` field.
2. Get the newest copy of the agent: `hive agents install <name> --yes`.
3. Open the agent's page in **Settings → Plugins**. If it shows an error, follow it.
4. Close the agent's tile and start it again, so it starts with the new copy.

**Check:** ask the agent to do something that needs your permission. Its tile turns amber, and the bell in the Layers panel counts 1.

More in [Know who is waiting](https://hivemind.griiken.com/guide/know-who-is-waiting/).

## The app does not open on macOS [#the-app-does-not-open-on-macos]

**Why:** The app is not signed with an Apple Developer certificate. A download your browser saved is marked as quarantined, and macOS then says `hivemind is damaged and can't be opened`. The installer removes that mark for you; a zip you downloaded yourself keeps it.

**Fix:** install with the installer instead of the zip:

```bash
bash <(curl -fsSL https://hivemind.griiken.com/install.sh)
```

Or, for the app you already unpacked, remove the mark yourself:

```bash
xattr -dr com.apple.quarantine ~/.hivemind-app/hivemind.app
```

**Check:** `hivemind` opens the app.

Hivemind needs macOS 13 or later on Apple Silicon: see [System requirements](https://hivemind.griiken.com/guide/system-requirements/).

## The AppImage does not start [#the-appimage-does-not-start]

**Why:** An AppImage started by itself needs `libfuse2`, which newer Ubuntu releases leave out. Its Chromium sandbox also needs a helper owned by root. Without it, the app stops with `SUID sandbox helper binary was found, but is not configured correctly`.

**Fix:** install with the installer. It unpacks the AppImage, so it needs no `libfuse2`, and starts it with `--no-sandbox`:

```bash
bash <(curl -fsSL https://hivemind.griiken.com/install.sh)
```

To keep running the AppImage by hand, start it with `--no-sandbox`:

```bash
./hivemind-*-x86_64.AppImage --no-sandbox
```

**Check:** the window opens, and `hivemind` starts it again later.

## Agents stopped after an upgrade [#agents-stopped-after-an-upgrade]

**Why:** Your terminals and agents run in a background process that keeps them alive while the app closes or updates. A restart of the computer ends that process. Some agents can resume their conversation; the rest start fresh.

**Fix:**

1. To see whether the background process runs, run `hive daemon status`.
2. To see which agents Hivemind still holds, run `hive ctl agents`.
3. A black tile with **Resume** is an agent put to sleep. Press **Resume**, or run `hive ctl wake <tile>`.
4. To pick up an older conversation, list it with `hive ctl sessions <agent>`, then start it with `hive ctl spawn --agent <agent> --resume <session>`.

**Check:** the agent's tile shows its conversation again.

## hive ctl says the app is not running [#hive-ctl-says-the-app-is-not-running]

**Why:** `hive ctl` drives the running app, or `hive host`. With neither running, it exits 3 with `hivemind app not running (no socket at …)`.

**Fix:** open the project with `hivemind .`, or start the host with `hive host run`. Issue commands such as `hive list` work without either.

**Check:** `hive ctl agents` exits 0.

## No agent to start [#no-agent-to-start]

**Why:** No agent ships in the app. Hivemind adds an agent when it finds that agent's own program on your `PATH`.

**Fix:**

1. Install the agent's own program, such as `claude` or `codex`.
2. Add the agent: `hive agents install <name> --yes`. To see what Hivemind finds, run `hive agents list --found`.
3. If the agent is in the list but not in the menus, it is switched off or failed to load. Its page in **Settings → Plugins** says why.

**Check:** pressing `2` on the canvas starts the agent.

## Issue commands fail [#issue-commands-fail]

| Error | Fix |
|---|---|
| `no .hivemind/ found` | Run `hive init --prefix XX` in the project. `XX` is 2 to 10 capital letters or digits, starting with a letter. |
| `.hivemind/ already exists at …` | Use it. A bare `hive init` refreshes the agent skills. |
| `move` refused | The issue has sub-issues. Move them first with `hive link <child> --parent none`, or use `--copy`. |
| Another project's id not found | Run `hive workspace register` in both projects, then check `hive workspace list`. |

## A machine will not connect [#a-machine-will-not-connect]

**Fix:** press **Sign in** on the machine, or run `ssh <user@host>` once to accept its host key. Then run `hive machine check <name>`: it shows what it finds.

If its terminals end whenever the connection drops, `hive` could not be put on the machine. **Manage machines…** says why: often no `curl` or `wget`, or a full disk.

**Check:** `hive machine check <name>` prints the machine's platform and `hive` version.

## A token is refused [#a-token-is-refused]

| Error | Fix |
|---|---|
| `FORBIDDEN` on hello | The token is wrong, revoked or expired, or does not reach that workspace. Make a new one. |
| `BAD_REQUEST` on hello | Name the workspace's folder, and open it in the app first. |
| `FORBIDDEN` on a call | The token's role does not allow it. See [Methods by role](https://hivemind.griiken.com/guide/api-methods/). |

## Other things you may see [#other-things-you-may-see]

| What you see | Why and fix |
|---|---|
| `hive ctl read` exits 4 | The agent had not finished replying. Run `read` again. |
| `hive ctl read` exits 5 | The tile was closed while you waited. |
| A workflow is refused with exit 7 | That agent does not tell Hivemind when it finishes replying. Pick one from [Run agents](https://hivemind.griiken.com/guide/agents/). |
| An agent cannot use the browser | Switch on the Browser tool and **Agent browser control** on its page, restart, and open a Browser tile. |
| A view is missing | Its page in **Settings → Plugins** says why. `hive plugins list --kind view` shows load errors. |
| A Browser tile reloads after you switch views | Expected: tabs and history stay, the scroll position does not. |
| A site in a Browser tile cannot use the camera, microphone, location or notifications | You blocked it, did not answer, or it checks without asking. Open **Site permissions** by the address and choose **Allow**, or **Ask** to be asked again. See [Sites in a Browser tile](https://hivemind.griiken.com/guide/security-and-privacy/#sites-in-a-browser-tile). |
| Where a download from a Browser tile went | Your Downloads folder, with a number added when the name is taken. The tile says what it saved: **Show in folder** opens it there. While an agent that asked for downloads is at work in that tile, its folder gets them instead. |
| A site in a Browser tile says `prompt() is not supported` | The app has no `prompt()` box. Open the site in your own browser. |
| A `mailto:`, meeting or app link in a Browser tile does nothing | The site asked to open it in another program and you blocked it, or did not answer. Choose **Allow** in **Site permissions** by the address, then click the link again. |
| A site cannot use a USB, serial or input device, choose a speaker, or share your screen | A Browser tile never gives these. Open the site in your own browser. |
| `no PTY daemon on … — start one with hive daemon start` | Run `hive daemon start`. |

<LastValidated />