Help
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.
On this page
Start here when something isn’t working. Run doctor, find the line that isn’t a ✓, and look it up below.
wheems doctorEach 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 lsandhc attach <session>: what an agent is doing right now.
System
Link to “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. |
| 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. |
Herdr core
Link to “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. 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
Link to “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
Link to “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
Link to “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. |
| 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
Link to “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
Link to “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
Link to “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
Link to “Common problems”Nothing happens when I message the bot
Link to “Nothing happens when I message the bot”No 👀 reaction means the message never reached an agent. In order:
wheems service status: is it answering?wheems service logs: look forIgnored a message on slack from U…, who is not in allowed_users, orthe bot cannot see channel ….- In a channel, has the bot been invited?
/invite @Wheems, thenwheems service restart. - Did you change config or invite the bot after the service started?
wheems service restart. - Did the message have a file attached? Those are ignored today.
The full table is in Connecting Slack.
I get 👀 but no answer
Link to “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
Link to “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.
launchd tries again every 30 seconds.
Search finds nothing I know is there
Link to “Search finds nothing I know is there”- New notes are found once filed and indexed.
wheems kb reindexforces 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
Link to “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.