Fix common errors

This page lists the errors a new user is most likely to meet. Find the text you see in the heading. Ask your coordinator first. Your coordinator is the agent you talk to, which starts the other agents, hands out work and reports back to you. It can run the fix for you. The typed commands are for setup, and for when the coordinator cannot reach Thrum.

For problems with one area, see identity errors, sync problems and email bridge problems.

Thrum does not respond

“thrum daemon is not running”

The full message continues “Start it with: thrum daemon start”. The daemon is Thrum’s background process on your machine. In the web UI, the Agents grid shows “Daemon unreachable — reconnecting…” with a Retry button, and the footer shows DISCONNECTED. Thrum’s web UI is the page you open in your browser to see your agents and their messages. If the page does not load at all, the daemon is stopped.

Cause. The Thrum daemon, the background process Thrum runs on your machine, has stopped. It can stop for several reasons, such as a reboot or a crash. Agents cannot send or read messages until it runs again.

Fix.

1. Ask the coordinator: “Start the Thrum daemon and tell me when the agents are back.”

2. If the coordinator cannot reach Thrum, start it yourself in a terminal in the repository:

   thrum daemon start

3. If it stops again, ask the coordinator to read the daemon log and tell you the reason. The typed form is thrum daemon logs.

Check it worked: thrum daemon status prints Daemon: running, and the Agents grid fills in after you press Retry.

“daemon is already running (PID …) for repo …”

Cause. You started the daemon for a repository where it is already running. Nothing is wrong.

Fix. Do nothing. To see its state, ask the coordinator or run thrum daemon status. To restart it on purpose, ask the coordinator, or run thrum daemon stop, then thrum daemon start.

The steps to restart it after an update are in When you update Thrum later.

“thrum not initialized - run ‘thrum init’ first”

A shorter form reads “thrum not initialized in this repository”.

Cause. The folder has no Thrum setup yet, or you are in a different folder than your repository.

Fix. Change to your repository folder. If it is new, run thrum init there. The quickstart walks through the setup. No coordinator exists yet at this stage, so this one is a typed step.

“tmux is required but not found on PATH.”

You see this when thrum init starts. The message goes on to list install commands and ends “Then re-run: thrum init”.

Cause. Thrum runs each agent in tmux, a terminal tool that keeps sessions alive. It is not installed, or your shell cannot find it. macOS and Linux only.

Fix. Install tmux with the command the message marks “detected on your system”. The choices are:

• brew install tmux (Homebrew, macOS and Linux)
• sudo port install tmux (MacPorts, macOS)
• apt install tmux (Debian and Ubuntu)

Then run thrum init again. Setup happens before a coordinator exists, so this is a typed step. See Run agents in tmux for what tmux does for you.

Check it worked: thrum init prints tmux: found at followed by a path, then continues.

Messages are refused

“unknown recipient: @name — send to agents directly with –to @agent_name”

Cause. The name does not match a registered agent. The usual reasons are a typo, an agent that was removed, or a role used as a name (@coordinator or @reviewer). Thrum does not send a message to every agent with a role. Each message goes to one agent, named exactly.

Fix.

1. Ask the coordinator: “Which agents exist, and what is the exact name of the one I want?” The Agents grid lists the names.
2. Repeat the request with the exact name, for example “Ask reviewer_api to review the auth module.”
3. If the agent is on another machine, check that the machines are paired. See Fix sync problems.

Check it worked: the message goes out without the error, and the named agent shows it in its Messages tab.

“no recipient specified and no local coordinator found”

The message ends with: address the message explicitly with @<agent>.

Cause. A message was sent with no recipient, and Thrum sends such messages to your coordinator. No coordinator is registered on this machine.

Fix. Ask the coordinator to start, or start one as described in the quickstart. Until then, name the agent that should get the message.

“no recipient specified and multiple local coordinators found”

The message lists the coordinators it found, then ends with: address the message explicitly with @<agent>.

Cause. A message with no recipient goes to the coordinator, but this machine has more than one. Thrum will not guess.

Fix. Name the coordinator you mean when you ask an agent to send. If you keep a second coordinator by mistake, ask the main coordinator to retire it.

An action needs a Pro licence

These errors mean you used something Pro adds. Pricing lists what Pro adds and the length of the trial.

“state.write: not entitled for this machine”

The same text appears with queue.write or dashboard.write in place of state.write. The full text reads “(create/update requires a Pro license or an OSS grant for this repository; reading and deleting stay free)”. An OSS grant is Pro free for a public repository: it gives you the Pro features in that one repository.

Cause. Pro is the paid plan. Writing needs it: changing an agent’s personal state (state.write), the work queue (queue.write) or the document on the Dashboard tab (dashboard.write) needs a Pro licence on this machine. Personal state is a short note an agent keeps about its own status and next actions. The work queue is the list of work an agent has committed to. The Dashboard tab shows a document the agent writes. You can still read what is saved, and delete it.

Fix.

1. Ask the coordinator whether this machine has a licence: “Is Thrum licensed on this machine?” The typed form is thrum license status. It prints license: not activated when there is none.

2. To activate, run this on the machine. It prints a link. Open the link in your browser and click Activate there. That step is yours; a coordinator cannot do it for you:

   thrum license activate

3. Ask the coordinator to repeat the action.

Check it worked: thrum license status no longer says not activated, and the action succeeds.

“memory.substrate requires a license”

The message ends with: run `thrum license` to activate.

Cause. Writing Memory needs a Pro licence on this machine, in the same way as above. Memory is saved, titled notes that later sessions and other agents can search. Reading Memory that is already saved stays free.

Fix. Follow the activation steps in the entry above.

Still stuck?

• Fix identity errors: a command is refused with an “identity guard” message, the check that a command comes from the agent that owns the folder it runs in.
• Fix sync problems: messages or agents do not cross machines.
• How Thrum works: what the daemon, the agents and the coordinator each do.