Troubleshooting nodes
Fix the common problems installing, joining and running mojoup-node.
Start with the node's own check. It tests the machine and names the fix for each problem it finds:
mojoup-node doctor
mojoup-node status
mojoup-node logs -n 200Installing
The install script was not told where the packages are. Set MOJOUP_NODE_SOURCE (or -Source on Windows) to your install source. See Install a node.
The node is linked from ~/.local/bin (or /usr/local/bin as root). Add that folder to your PATH, or open a new terminal. On Windows, open a new PowerShell window so the updated user PATH is read.
The script refuses an archive whose digest does not match SHA256SUMS, a file that does not match the package's manifest, a Windows executable that is not validly signed by Mojo Up, and a preview build on the stable channel. Each is deliberate: get a fresh copy of the install source, or set the channel to preview if you meant to install a preview build.
Nodes run on 64-bit Windows (x64), Linux (x64 and arm64) and macOS (Intel and Apple silicon) only.
Joining
Your email's domain does not publish a discovery record. Join with the platform's address instead: mojoup-node join --url https://…. Your administrator can give it to you. For Mojo Up AI Cloud, use --cloud.
The node waits up to 24 hours for an approval. Someone allowed to approve nodes must open the page the node printed, or find it under Nodes → Pending in the console. If you opened the page without that permission, choose Pass to an approver so it reaches someone who can.
A Cloud node joins the organisation that was active in the Cloud console when you approved it. A node serves one organisation only. To move it, stop the node and join it again from a fresh state directory, switching to the right organisation at the top of the console's sidebar before you approve.
The approver refused the node, or the join key was refused (expired, revoked or used up if it was single use). Ask for a new approval or a new key.
Copy the whole invitation line, starting mojoup-hub:. An invitation works once and for 15 minutes; after that, ask the hub's owner for a new one. After five wrong codes in a minute, wait a minute before trying again.
Do not join. The address does not lead to your team's hub, or the hub's certificate changed. Check the address with the hub's owner and compare the fingerprint on the hub's Settings → Team page.
Running
The organisation refused this machine as a node, for example because its state directory holds a workbench's sign-in rather than a node's. Join it as a node with mojoup-node join from its own state directory.
Install at least one agent tool on the node, such as Claude Code (npm i -g @anthropic-ai/claude-code), Codex or GitHub Copilot CLI, and sign it in as the user the node runs as. doctor prints the sign-in command for each tool that needs one. A tool that is an npm package needs Node.js on the machine.
Agent worktrees take room. doctor warns under 5 GB free and fails under 0.5 GB. Free space, or move the state directory with --state-dir or MOJOUP_NODE_STATE_DIR.
The node is joined but its mesh registration has not been approved. It tries again at the next heartbeat; an approver can approve it under Nodes in the console. If the node's join key was revoked, the node is back in Pending until someone approves it.
doctor reports the platform as unreachable. The node needs outbound HTTPS to the platform. Behind a proxy, set the proxy for the node's environment, and set platform.mesh.proxy if the mesh agent needs one other than the system's.
The node keeps its secrets key in a file when it found no operating-system store. Run mojoup-node secrets migrate to move it into DPAPI, the Keychain or the Secret Service where available.
A systemd user unit only runs while you are logged in unless lingering is on. service install tries to turn it on and otherwise prints the one command to run with sudo. Or install the service with --system as root.
That is by design: a request nobody answers is denied after node.approvalTimeoutSeconds (five minutes), or node.approvalHoldSeconds (30 minutes) once it reached the organisation's inbox. Raise them with mojoup-node config set if your team needs longer.
The updater tries the new version first and keeps the old one if it does not start within two minutes. mojoup-node status and logs/update.log in the state directory say why. An update refuses to run while the node is running in someone's terminal: stop it, or run it as a service.
See Sandboxed nodes for what a sandbox needs. Under WSL in mirrored networking mode, sandboxes are not available.
Still stuck? See Support.