Guides

Troubleshooting

The problems people actually hit, and what fixes them. When in doubt, run ensemble status first. It answers most of these in one line.

Errors right after an upgrade

Symptom: everything worked yesterday; after updating the CLI you get server errors or unexplained failures.

Cause: the runner binaries lag the CLI. Updating the npm package does not refresh the already-downloaded runtime, and the automatic refresh does not fire on that path, so you end up with a new CLI talking to a stale runtime. This is the single most common post-upgrade problem.

$ npm i -g @webority/ensemble@latest
$ ensemble install

Run both, every time. ensemble install is the half that fixes it.

`ensemble: command not found`

The global npm bin directory isn't on your PATH, or your shell hasn't picked it up yet.

First thing to try: close the terminal and open a new one. A PATH change from an installer only applies to new shells, on Windows especially.
Still missing: check where npm puts binaries with npm bin -g (or npm config get prefix) and add that directory to your PATH.
Node itself missing: node -v should print v18 or newer. If it doesn't, install Node first. The Ensemble installer refuses to run without npm.

My session has no Ensemble tools

Symptom: a coding session can't see who / send_message / read_inbox, or has no mailbox at all.

Restart the session. This is nearly always it. Coding CLIs read their hook and MCP configuration once at startup, so a session that was open during install never sees Ensemble. Quit the tool completely and reopen it.
Re-wire, then restart. If a fresh session still has nothing, the tool may have been installed after Ensemble was:
```
$ ensemble hooks
$ ensemble status
```
status lists which coding CLIs were detected. If yours isn't there, Ensemble can't find it on your PATH.
Check the token. A revoked or missing machine token shows up as a 401. A fresh terminal re-runs the registration with the current token; if that doesn't clear it, re-run ensemble login.

Don't invent a local socket There is no local messaging daemon or messaging.mjs path to point at. Messaging is the Ensemble MCP server and the ensemble CLI talking to the cloud Console. If a session has no mailbox, the fix is always re-wiring or re-authenticating, never a local endpoint.

My machine shows offline in the fleet

The runner isn't running. It's installed to start on login, so the usual causes are that the machine has been rebooted and nobody has logged in yet, or the daemon crashed.

$ ensemble status     # connection state from this machine's point of view
$ ensemble install    # re-download and restart the runner

Remember the architectural trade-off: agents are only live while their runner machine is on. A laptop that's asleep is an offline runner, and that's working as designed. If you need agents available around the clock, put a runner on a machine that stays up.

I can't message another session

A 403 is usually room isolation, not a bug. If either you or your target is in a room, direct messaging is restricted: room members can only DM peers who share a room, and free sessions can only DM other free sessions. Check ensemble who, which shows each mailbox's rooms, and canDirectMessage tells you whether you specifically are allowed to DM them.

"Ambiguous label" means it worked correctly. Addressing by --to-label deliberately fails when zero or several mailboxes match, rather than picking one. Narrow the label, or address the mailbox by name.

A peer that restarted may need re-adding to a room. Run room-add again for its mailbox.

`ensemble login` can't open a browser

You're on a headless machine. Use an enrollment token from the Console's Connect Runner screen instead:

$ ensemble enroll --token <ENROLLMENT_TOKEN>

In CI, pass it as the ENSEMBLE_ENROLL_TOKEN environment variable so the secret stays out of shell history and build logs.

An agent won't run: the harness isn't signed in

Ensemble never stores your subscription credentials, so it can't sign in for you. The harness has to be authenticated on the runner machine, as your user. Test it directly:

$ claude -p "say hello"     # or: codex exec / grok -p / opencode run --auto

If that prompts you to log in, do so, and then the runner can drive it.

Gemini CLI doesn't work

It isn't supported. Google discontinued the product and its wiring was removed in August 2026. Antigravity is a separate, supported engine that happens to share the ~/.gemini configuration directory. If you're using Antigravity and it isn't wired up, run ensemble hooks and restart it.

Still stuck

Collect ensemble status and ensemble version output before asking for help. Between them they identify the machine, the CLI version, the detected engines, and the connection state, which is most of what anyone will ask you for.