Troubleshooting
Find the message you see on this page. Where part of a message changes, such as a name or a number, it is written here as ….
Run monoclaw doctor first
Section titled “Run monoclaw doctor first”On the computer that has the problem, run:
monoclaw doctorIt checks Node.js, the program itself, Claude Code and its sign-in, the connection to your account, the folders, the background service, each module, and ffmpeg where a module needs it. Where it can, it repairs what it finds.
How to read it:
✓The check passed.•A note, not a problem. For example,Claude Code is not installed separately (fine: MonoClaw uses its own copy).✗Something to fix. The line under it, starting with→, is the fix.
It ends with All good. or with how many things there are to fix. Fix them from the top down, then run it again. To look without changing anything:
monoclaw doctor --no-repairIf the computer is connected under a profile, put the profile in every command, as in monoclaw --profile acme doctor. See One computer in several spaces.
Installing
Section titled “Installing”MonoClaw needs Node.js 22 or newer. Install it, open a new terminal and run this again.
Section titled “MonoClaw needs Node.js 22 or newer. Install it, open a new terminal and run this again.”Your Node.js is older than 22. Nothing was installed. Install a newer one as shown in the Quick start, open a new terminal so it is found, and paste the same command again.
The terminal says npx is not found
Section titled “The terminal says npx is not found”npx comes with Node.js, so Node.js is not installed, or the terminal was opened before it was. Install it as shown in the Quick start, open a new terminal and paste the command again.
npm isn't allowed to install here (permission denied). …
Section titled “npm isn't allowed to install here (permission denied). …”npm tried to install into a folder your user cannot write to, and reported EACCES. Do not use sudo. Install Node.js with Homebrew on macOS (brew install node) or with nvm on Linux (nvm install 22), which keep it in your own folders. Then open a new terminal and run the command again.
npm could not install …
Section titled “npm could not install …”npm failed for another reason, and the rest of the message is what npm said. Fix that and run the command again.
Note: … is not on your PATH, so the monoclaw command won't be found until it is added.
Section titled “Note: … is not on your PATH, so the monoclaw command won't be found until it is added.”The program is installed and the computer is connected, but your terminal does not look in the folder npm installs commands into. The machine runs; only typing monoclaw will not work until you add the folder named in the message to your PATH.
Host's copy of Claude Code is missing …
Section titled “Host's copy of Claude Code is missing …”MonoClaw brings its own copy of Claude Code, as a large optional download that npm sometimes skips. monoclaw doctor installs it when it finds it missing. If that fails, run the npm install -g command shown on the line under the message. Until then the machine uses the claude on your PATH, if there is one.
Connecting
Section titled “Connecting”That enrolment token was not found or has expired. Make a new one from Add a machine.
Section titled “That enrolment token was not found or has expired. Make a new one from Add a machine.”The token in the command is used up or too old. A command works once, for an hour. Go back to the app, copy the command it shows now and run that.
No token. Copy the whole command from Add a machine in MonoClaw: it ends with a one-time token.
Section titled “No token. Copy the whole command from Add a machine in MonoClaw: it ends with a one-time token.”The command was cut short when it was pasted. Copy the whole command from the app again.
This computer was not connected. If the token has run out, copy a new command from Add a machine.
Section titled “This computer was not connected. If the token has run out, copy a new command from Add a machine.”The step that connects the computer failed. The lines above this one in the terminal say why; the usual reason is the token, as in the first entry here.
The background service could not be installed here. Run it in this terminal instead: …
Section titled “The background service could not be installed here. Run it in this terminal instead: …”The computer is connected, but the machine could not be set to run in the background on this system. The lines above say why. Start it in the terminal with monoclaw start; it runs until you close that terminal.
Not enrolled. Run: …
Section titled “Not enrolled. Run: …”You ran a command that needs a connected machine, but this computer is not connected to an account yet. Get the command from Machines, then Add a machine, in the app. If you connected under a profile, add --profile and its name to the command you ran.
This computer's enrolments are under profiles: …
Section titled “This computer's enrolments are under profiles: …”This computer is connected to more than one space, each under its own profile, and the command did not say which one it meant. Name one, as the message shows:
monoclaw --profile guestlab doctorWith a single enrolment you never need to name it. See One computer in several spaces.
This computer is already enrolled in …
Section titled “This computer is already enrolled in …”The computer is already a machine in that space. Nothing changed and the token was not used. If the machine shows offline in the app, start it:
monoclaw service installrouter URL … is not https.
Section titled “router URL … is not https.”The address after --router does not start with https://. MonoClaw refuses to send your messages over a connection that is not encrypted. Use the command exactly as the app shows it; the address is https://command.monoclaw.ai.
The app keeps waiting and the machine does not appear
Section titled “The app keeps waiting and the machine does not appear”The machine has to be both connected and running.
- Look in the terminal for a line that starts
Enrolled as. If it is not there, the command stopped earlier: find the first error above and look it up on this page. - If it is there, the machine may not be running. Start it with
monoclaw service install. - Run
monoclaw doctorand fix what it reports.
The machine shows offline
Section titled “The machine shows offline”… is offline right now.
Section titled “… is offline right now.”The app could not reach the agent’s machine. The same thing shows on the machine’s page as … is offline · Agents on it are paused. Messages you send are queued and delivered when it is back.
Check that the computer is on, awake and online. Then, on that computer:
monoclaw statusIf it is not running, start it with monoclaw service install. On a Linux server, see the next entry.
The machine goes offline when you log out
Section titled “The machine goes offline when you log out”On Linux a user’s background services stop when the user logs out, so a server set up over ssh drops offline when you close the terminal. monoclaw service install turns this off for your user when the system lets it, and says so when it could not. monoclaw doctor shows the line This machine goes offline when you log out of this computer (linger is off for your user) while it is still a problem. Run this once on the server:
loginctl enable-linger $USERA laptop that sleeps is offline while it sleeps. Queued messages are delivered when it wakes and reconnects.
MonoClaw is already running for this machine …
Section titled “MonoClaw is already running for this machine …”You started the machine a second time. Only one copy can run per machine. Usually the background service is already running and you then ran monoclaw start in a terminal. Either leave the background service running, or stop it first:
monoclaw service uninstallThen start it again the way you want it: monoclaw service install for the background, or monoclaw start in a terminal. If nothing is running, delete the file the message names and start again.
another MonoClaw host connected with this machine's enrolment …
Section titled “another MonoClaw host connected with this machine's enrolment …”This line is in the machine’s log. The same connection was used from two places, for example a copy of the settings folder on a second computer, so this copy stopped. Run one copy per machine. To use a second computer, add it from Add a machine so it gets its own connection.
router rejected credential …
Section titled “router rejected credential …”This line is in the machine’s log. The machine was removed in the app, so its connection no longer works. Add it again from Machines, then Add a machine.
Claude
Section titled “Claude”None of your machines can run agents yet.
Section titled “None of your machines can run agents yet.”No machine in this space has an agent module. Choose Add Claude (subscription) beside a machine on that screen, or open the machine’s page and choose Add module. On the machine itself the same thing is:
monoclaw modules add claude-subscriptionNot logged in to Claude
Section titled “Not logged in to Claude”The Claude Code this machine uses is not signed in. In the app the same problem reads Claude Code is installed but not logged in. On that computer, run:
monoclaw claude auth loginCheck on the machine’s page in the app checks again at once. On a server without a browser the command still works: it prints a link: open the link on any device, sign in, and paste the code it gives you back into the terminal.
Claude Code is not available
Section titled “Claude Code is not available”The machine found no Claude Code: its own copy is missing and there is none on the PATH. Run monoclaw doctor on the machine, which installs the copy MonoClaw uses, then sign in as above. monoclaw doctor reports the same thing as No Claude Code to run sessions with, and the sign-in command as No Claude Code on this machine yet. ….
Could not check login state
Section titled “Could not check login state”The machine could not ask Claude Code whether it is signed in. To see what is wrong, run this on the machine:
monoclaw claude auth statusThat does not look like an Anthropic API key; it starts with sk-ant-.
Section titled “That does not look like an Anthropic API key; it starts with sk-ant-.”The key you entered for Claude (API key) is not an Anthropic key, or part of it is missing. Copy it again from the Anthropic Console.
Permission mode "…" is not allowed on this machine …
Section titled “Permission mode "…" is not allowed on this machine …”The agent asked for a permission mode this machine does not accept, so the machine used another, named in the message. To see what the machine accepts:
monoclaw config showThis machine already runs … sessions (its limit).
Section titled “This machine already runs … sessions (its limit).”A machine runs a set number of agents at once, 8 unless you change it. Wait for one to finish, or raise the limit on the machine and restart it:
monoclaw config set maxSessions 16Folders
Section titled “Folders”No folders exposed
Section titled “No folders exposed”The machine has no allowed folder, so there is nowhere for an agent to work. In the agent form the same thing reads … exposes no folders yet. Add one on the machine and restart it:
monoclaw roots add ~/commandnot a folder: …
Section titled “not a folder: …”The folder you tried to add does not exist. Create it first, then add it.
Not exposing …: it contains this host's config folder …
Section titled “Not exposing …: it contains this host's config folder …”The folder you named contains MonoClaw’s own settings, which agents must not be able to change. Your whole home folder is the usual case. Name a folder inside it instead, such as ~/command.
… is outside the folders … allows
Section titled “… is outside the folders … allows”The folder chosen for the agent is not inside one of the machine’s allowed folders, or not inside the folders its connection is limited to. Choose a folder with Browse…, or add the folder on the machine with monoclaw roots add. You may also see … is outside the folders this machine (or the provider account) allows.
folder … does not exist on this host
Section titled “folder … does not exist on this host”The agent’s folder was moved or deleted on the machine. Put it back, or add a new agent in the folder you want.
A folder you added does not show in the app
Section titled “A folder you added does not show in the app”Restart the machine after changing its folders: run monoclaw service install again.
Voice and other modules
Section titled “Voice and other modules”No modules on this machine (a bare host runs nothing)
Section titled “No modules on this machine (a bare host runs nothing)”A new machine can do nothing until you add a module. Open the machine’s page and choose Add module, or see what there is on the machine:
monoclaw modules list --allffmpeg is missing (Kokoro and Parakeet need it)
Section titled “ffmpeg is missing (Kokoro and Parakeet need it)”Kokoro and Parakeet use ffmpeg to read and write audio. On the machine’s page the module shows Needs setup. Install ffmpeg on that machine: brew install ffmpeg on macOS, sudo apt install ffmpeg or your distribution’s package on Linux, winget install --id Gyan.FFmpeg -e on Windows. Then run monoclaw doctor.
Install failed: …
Section titled “Install failed: …”A module’s download or installation did not finish, and the module shows Error. The rest of the message says why, for example installing the voice library timed out after 10 minutes. Fix what it names, then try again:
monoclaw modules add kokoroUse the module’s own name in place of kokoro.
Not installed yet: add the module again to download it
Section titled “Not installed yet: add the module again to download it”The module is on the machine’s list but its files are not there. Add it again, as above.
Waiting for the key
Section titled “Waiting for the key”A module that uses an API key has a connection with no key yet. On the machine’s page choose Enter key. The machine must be online to receive it. Or enter it on the machine with monoclaw modules key followed by the connection’s id, which monoclaw modules list shows.
… is offline. Secrets are relayed live and never stored; try again when it is online.
Section titled “… is offline. Secrets are relayed live and never stored; try again when it is online.”You entered a key in the app while the machine was offline. The service does not keep keys, so it could not hold yours until later. Enter it again when the machine is online.
ElevenLabs refused the key. Enter it again.
Section titled “ElevenLabs refused the key. Enter it again.”ElevenLabs did not accept the key: it is wrong, or it was revoked. Choose Replace key on the machine’s page. fal refused the key. Enter it again. is the same for fal.
… is at its monthly cap: …
Section titled “… is at its monthly cap: …”The key has reached the monthly cap you set on the machine, so the machine refused the work. Wait for next month, or raise the cap on the machine with monoclaw modules cap, as the message shows. The module’s page explains caps.
The ElevenLabs account has used this month's characters.
Section titled “The ElevenLabs account has used this month's characters.”This limit is ElevenLabs’ own, on your account with them, not a MonoClaw cap.
Voice needs … online
Section titled “Voice needs … online”The agent’s voice is made on a machine that is offline. There is no audio until it is back. To use another machine, change the voice on the agent’s card.
… has no voice yet. An owner can choose one on …'s card.
Section titled “… has no voice yet. An owner can choose one on …'s card.”Nobody has chosen a voice for this agent. See Give an agent a voice.
Couldn't transcribe · the agent will listen to the audio
Section titled “Couldn't transcribe · the agent will listen to the audio”Your voice message was not turned into text: the project has no transcription set, its machine is offline, or the module failed. The agent gets the audio instead. See Choose where voice messages are transcribed.
The multilingual model is downloading on this machine …
Section titled “The multilingual model is downloading on this machine …”Parakeet’s 25-language model is fetched the first time it is used. Try again in a few minutes.
Updates
Section titled “Updates”Machines update themselves. See Machines.
… is older than the minimum this router accepts …
Section titled “… is older than the minimum this router accepts …”The machine’s version is too old to connect, and this copy cannot update itself because it was not installed with npm. Install the current version:
npm install -g --ignore-scripts @monoclaw/machine@latestThen restart the machine.
updated twice but still running …
Section titled “updated twice but still running …”The update was installed by a different npm than the one the background service runs from, which can happen after changing Node.js versions. Run npm prefix -g to see where npm installs, as the message says. Then, in a terminal where monoclaw doctor shows the current version, run monoclaw service install again so the service uses that copy.
… runs an older MonoClaw that doesn't list what it can install.
Section titled “… runs an older MonoClaw that doesn't list what it can install.”The machine’s version is from before modules could be added from the app. Update it on the machine, then restart it:
monoclaw updateA machine stays on an old version
Section titled “A machine stays on an old version”Updates wait until agents finish what they are doing, and a machine that is offline cannot update. If Machines still shows Update after a day, run monoclaw update on the machine and restart it. A machine started with MONOCLAW_NO_UPDATE=1 skips updates that are not required.
Still stuck
Section titled “Still stuck”Write to hello@monoclaw.ai with the output of monoclaw doctor and the last lines of ~/.monoclaw/host/logs/host.log. Check the log for anything private before you send it.