# Troubleshooting

> Every check wheems doctor makes, what each failure or warning means and how to fix it, plus common problems in Slack and the service.

Start here when something isn't working. Run doctor, find the line that isn't a `✓`, and look it up below.

```bash title="Terminal"
wheems doctor
```

Each check shows as `✓` passed, `!` a warning, `✗` failed, or `-` skipped, with a hint on the line below. Doctor exits with `1` when any check fails; warnings don't fail it. `--quick` skips the Herdr core round trip, and `--json` prints the report as JSON.

The other places to look:

- `wheems service logs`: what the service did, and why it stopped.
- `wheems validate`: config errors, with file and line.
- `hc ls` and `hc attach <session>`: what an agent is doing right now.

## System

| Check | Message | Fix |
| --- | --- | --- |
| Node.js | `Node.js 22.12.0 is too old for Wheems. Use Node.js 22.16 or later in the 22 line, or 24 or later.` | Install Node 22 (22.16 or later) or 24, then reinstall Wheems and the service with it. See [Installation](https://wheems.dev/docs/installation/#if-your-default-nodejs-isnt-supported). |
| Node.js | `Node.js 23.11.0 can't run Wheems: no Node 23 release has SQLite full-text search, …` | Node 23 never works. Install Node 22 or 24. |
| SQLite search | `This Node.js (…) has SQLite without full-text search (FTS5), which Wheems's search needs …` | This Node build uses a SQLite without full-text search. Install Node 22.16+ or 24+ from nodejs.org, or a package that bundles Node's own SQLite. |
| platform | `win32 is not supported yet; Wheems runs on macOS (and Linux, apart from the service)` | Use a Mac. |
| platform | `Linux: the commands work, but the service runs under launchd on macOS only; …` (warning) | The service can't be installed on Linux yet; see [Running as a service](https://wheems.dev/docs/service/#linux). |

## Herdr core

| Check | Message | Fix |
| --- | --- | --- |
| hc installed | An error, with `Install Herdr core and make sure hc is on PATH.` | Install Herdr core from [herdr.dev/core](https://herdr.dev/core/). If it's installed somewhere unusual, set `herdr.binary` in `install.yaml`. |
| hc version | `hc 0.1.19 is older than the minimum 0.1.20` | `hc update` |
| Herdr core | `The running core is 0.1.19, older than the minimum 0.1.20` | `hc update`. It restarts an older core and keeps terminals running. |
| Herdr core | `The core does not answer: …` | `hc server status` to see why. |
| round trip | `A test session did not answer as expected …` or `A test session failed: …` | Herdr core is running but can't run a session. Try `hc run echo hello`. |
| pinned version | `install.yaml pins Herdr core 0.1.10, below Wheems's minimum 0.1.20, so 0.1.20 applies` (warning) | Set `herdr.version` to `0.1.20` or later, or remove it. |

## Config

| Check | Message | Fix |
| --- | --- | --- |
| install | `No install at /Users/you/wheems yet` (skipped) | Run `wheems setup`. Set `WHEEMS_HOME` or `--home` to check another folder. |
| install | `2 problems in /Users/you/wheems`, followed by each problem with its file | Fix each one. `wheems validate` shows line numbers. The service won't start until they're fixed. |

Common config problems:

| Problem | Fix |
| --- | --- |
| `Unrecognized key: "chanels"` | A typo. Unknown keys are errors. |
| `Account "chatgpt-subscription" is not in install.yaml` | Add the account to `install.yaml`, or use one that's there. |
| `Account "…" is not one of the workspace's accounts` | Add it to the workspace's `accounts`. |
| `Channel "chat" uses direct messages on "slack", which workspace "personal" already has` | Give this workspace a channel instead. |
| `Channel "chat" uses connection "…", which is not in install.yaml` | Use `slack`, or add the connection. |
| `No "chat" channel yet; every workspace gets one` (warning) | Add `channels.chat` to `workspace.yaml`. |
| `The chief of staff "chief-of-staff" has no file in agents/` | Create the agent file, or fix `chief_of_staff`. |
| `Skill "weekly-report" is not in the library` / `has no version 3 in the library` | Fix the pin in `skills.yaml`, or add the skill. |
| `Skill "…" is not in the workspace's skills.yaml` | Pin it in `skills.yaml` before listing it on an agent. |
| `21 skills is over the budget of 20` (warning) | Remove skills, or raise `skill_budget`. |
| `No engine driver "…" is installed yet` (warning) | Use `claude-code`, `codex` or `opencode`. |

## Agents

| Check | Message | Fix |
| --- | --- | --- |
| Claude Code | `claude is not installed or not on PATH` | `wheems setup` → **Engines**, or `npm install -g @anthropic-ai/claude-code`. |
| Claude Code sign-in | `Claude Code is not signed in, so agents on it cannot answer` | `claude auth login`, or `wheems setup` → **Engines**. |
| Claude Code sign-in | `Couldn't tell whether Claude Code is signed in (claude auth status didn't say)` (warning) | Update Claude Code, or run `claude` yourself to check. |
| Codex / opencode | Not installed | `wheems setup` → **Engines**. |
| Codex sign-in | `Codex is not signed in` | `codex login`, or `wheems setup` → **Engines**. |
| *workspace* folder | `Claude Code hasn't been told to trust the workspace folder, so its first session will wait for that answer at the Mac` (warning) | Open the engine in that folder once and say yes: `cd ~/wheems/workspaces/acme && claude`. Or `wheems setup`. |
| engines | `No agents yet` (skipped) | Create a workspace. |

## Channels

| Check | Message | Fix |
| --- | --- | --- |
| slack | `Not connected yet: no credentials saved for it` | `wheems setup` → **Channels** → **Slack**. |
| slack | `Slack refused the bot token: invalid_auth` (or `token_revoked`, `account_inactive`) | Connect again with a new bot token. See [Rotating the tokens](https://wheems.dev/docs/slack/#rotating-the-tokens). |
| slack allowed users | `Nobody is allowed to talk to agents yet, so every message is ignored` (warning) | `wheems setup`, or add member IDs to `allowed_users` in `install.yaml`. |
| *workspace* chat channel | `The app can't see acme-chat` | Check the channel's name in `workspace.yaml`, invite the app to the channel, then `wheems service restart`. |
| *workspace* chat channel | `The app isn't in acme-chat, so messages there never reach the chief of staff` (warning) | In the channel, type `/invite` and choose the app, then `wheems service restart`. Slack lists public channels the app isn't in, but sends it no messages from them. |
| chat | `No workspace has a chat channel yet` (skipped) | Create a workspace. |

## Knowledge

| Check | Message | Fix |
| --- | --- | --- |
| embeddings | `Search is keyword-only` (skipped) | Fine. To search by meaning too, `wheems setup` → **Knowledge**. |
| embeddings | `Can't use knowledge.embeddings in install.yaml: …` | Fix it, or `wheems setup` → **Knowledge**. Until then search is keyword-only. |
| Ollama | `Ollama isn't answering at http://127.0.0.1:11434, so search is keyword-only for now` | Start the Ollama app, or `ollama serve`. |
| Ollama | `Ollama doesn't have nomic-embed-text, so search is keyword-only for now` | `ollama pull nomic-embed-text` |
| *workspace* index | `Not built yet` (warning) | The service builds it when it starts, or `wheems kb reindex`. |
| *workspace* index | `… not the model in install.yaml` (warning) | The service rebuilds it at its next sync, or `wheems kb reindex`. |
| *workspace* index | `… passages have no vector yet, so they're found by keyword only` (warning) | The service adds them once Ollama answers. |
| *workspace* index | `Can't read it: …` | `wheems kb reindex` |

## Review

| Check | Message | Fix |
| --- | --- | --- |
| review | `2 skill proposals and 1 change to about-you.md wait for review` (warning) | `wheems review`. Never a failure. |

## Service

| Check | Message | Fix |
| --- | --- | --- |
| service | `Not running, so nothing answers in chat` (warning) | `wheems service install` |
| service | `Installed, but not answering` (warning) | `wheems service logs` to see why. Usually a config error or Herdr core not running. |

## Common problems

### Nothing happens when I message the bot

No 👀 reaction means the message never reached an agent. In order:

1. `wheems service status`: is it answering?
2. `wheems service logs`: look for `Ignored a message on slack from U…, who is not in allowed_users`, or `the bot cannot see channel …`.
3. In a channel, has the bot been invited? `/invite @Wheems`, then `wheems service restart`.
4. Did you change config or invite the bot after the service started? `wheems service restart`.
5. Did the message have a file attached? Those are ignored today.

The full table is in [Connecting Slack](https://wheems.dev/docs/slack/#troubleshooting).

### I get 👀 but no answer

The agent has the message but hasn't answered. Wheems usually posts a notice in the thread saying why:

| Notice | Fix |
| --- | --- |
| *The agent hasn't started on this yet. It may be waiting for an answer at the Mac: `hc attach t7`.* | Attach and answer: usually the folder trust question. |
| *The agent is waiting for an answer at the Mac, such as a permission prompt: `hc attach t7`.* | Attach and answer. Consider `permissions: auto`. |
| *The agent hit an error. Its session is `t7` in Herdr.* | Attach to see the error, such as a usage limit or sign-in. |
| *The agent finished without replying here. Its session is `t7` in Herdr.* | Attach to see what it did, then reply in the thread. |
| *The session ended without replying.* | Reply in the thread to resume it. |
| *There's no answer yet. Its session is `t7` in Herdr.* | opencode only: no answer after an hour. Attach to look. |

No notice at all? Run `hc ls` and attach to the newest session for the workspace.

### The service keeps stopping

`wheems service status` shows `loaded, not running`. Read `wheems service logs`. The usual causes:

- `The install has config problems; run wheems doctor` → fix them, `wheems service restart`.
- `Herdr core is not ready: …` → `hc server status`, `hc update`.
- `Could not connect to Slack: invalid_auth` → [rotate the tokens](https://wheems.dev/docs/slack/#rotating-the-tokens).

launchd tries again every 30 seconds.

### Search finds nothing I know is there

- New notes are found once filed and indexed. `wheems kb reindex` forces it.
- A match by meaning alone must be close enough. Try the words the page uses.
- Is Ollama running? Without it, search is keyword-only, and says so.

## Still stuck

Collect the output of `wheems doctor --json` and the end of `wheems service logs`, remove anything private (tokens never appear in either, but names and paths do), and open an issue at [github.com/wheems-dev/wheems/issues](https://github.com/wheems-dev/wheems/issues).