Troubleshooting

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

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.

REFERENCE https://hivemind.griiken.com/guide/troubleshooting.md

Start hereCopy Anchor Link

1. Check your version: hive --version. Then check the changelog: a newer release may fix it.
2. Look at the logs. 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.
4. Still stuck? Report a bug with what you found.

Find your problemCopy Anchor Link

An agent never shows as waitingCopy Anchor Link

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.

The app does not open on macOSCopy Anchor Link

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 <(curl -fsSL https://hivemind.griiken.com/install.sh)

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

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.

The AppImage does not startCopy Anchor Link

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 <(curl -fsSL https://hivemind.griiken.com/install.sh)

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

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

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

Agents stopped after an upgradeCopy Anchor Link

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 runningCopy Anchor Link

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 startCopy Anchor Link

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 failCopy Anchor Link

A machine will not connectCopy Anchor Link

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 refusedCopy Anchor Link

Other things you may seeCopy Anchor Link

Last validated for Hivemind 2026.10.3.