Troubleshooting
Find the symptom, then follow the steps. Error codes in brackets are what the AI client or app shows.
The device shows offline
- Linux: sudo systemctl status webrising-commender --no-pager and sudo journalctl -u webrising-commender -n 30 --no-pager. The service must be active; network access to wecommander.app over HTTPS must be allowed outbound.
- Windows and macOS: the app must be running; the agent runs inside it and stops when you quit. The Windows app restarts a stopped agent and keeps trying every 5 minutes; “Keep agent running” in the panel turns this on.
- Windows server (agent alone): the agent runs only while its user is signed in.
- A revoked device does not come back: install again and approve it as a new device.
Host key changed
The app warns before connecting when a server's key differs from the one you trusted. If the server was reinstalled or its key rotated, check the new fingerprint with the server's provider and accept it, or remove the old entry in Known hosts and connect again. Until then AI access to that server is refused (host_key_untrusted).
Approval requests do not arrive
- Check the dashboard's Approvals page: requests always appear there.
- Windows: send a test notification from the Management Center. If it does not appear, allow notifications for WECOMMANDER in Windows settings and make sure banners are on; an organisation policy can block them, and then the panel opens on new requests instead.
- E-mail: requests are e-mailed to admins and owners; check spam. Only admins and owners can approve.
- A request expires after 10 minutes (5 for SSH servers); the AI must try again to create a new one.
- A request for an SSH server is shown only to the person whose computer shares it.
The AI cannot reach an SSH server
- connector_offline: the computer sharing the server is off, asleep, or the app is closed or signed out.
- host_key_untrusted or needs_credential: connect once in the app, trust the host key and save the password or a key without a passphrase.
- unsupported_for_target: that tool is only for agent devices.
- A read-only shared server refuses every change.
Commands are refused
- approval_required: approve the request, then let the AI repeat the call.
- safety_net_blocked: the command is on the safety net list. Run it yourself, or turn the safety net off for that device with your password if you really mean it.
- Outside the allowed folders: the path is outside the device's allowed folders; change them with sudo wecommander-setup --allowed-root on Linux.
- Refused by the device: commands or file writes are switched off on that device (--no-commands, --read-only).
- run_as_root_unavailable or device_not_root_capable: run the --allow-root command on the machine first, then turn root on in the dashboard.
- browser_session_required: changing permissions is done by an admin in the browser, never by an AI or API key.
Local AI client cannot connect (Windows)
- wecommander_not_running: open the WECOMMANDER app; local AI access works while it runs.
- client_not_allowed or client_denied: allow the client in the app (Settings → AI); a denied client is refused until you forget it.
- After moving or updating the app, Settings → AI offers to fix a client config that points to an old path.
Updates
- If an update stops with a checksum message, nothing was changed; try again later.
- Linux agent: run the install command again; the device identity is kept.
- Store copy: updates come from the Microsoft Store.
Limits
- monthly_tool_call_limit: the Free plan's monthly tool calls are used up; upgrade or wait for the reset.
- quota_exceeded or billing_required: a device, member or key limit was reached, or the plan needs attention; see Plans & billing.
- scheduled_task_limit: the plan's scheduled task limit was reached.
- Frequently asked questions: Answers about connecting AI assistants to your computers and servers with WECOMMANDER: safety, supported systems, clients and local mode.
- Agent: install, update and options: The WECOMMANDER agent on Windows, macOS and Linux: how it is installed and updated, the user it runs as, allowed folders, read-only and no-command switches, --allow-root, and checking its status.
- Approvals: web, e-mail and desktop notifications: How a high-risk AI action waits for a person, where approval requests arrive (dashboard, e-mail, Windows and macOS notifications, Linux Management Center) and what one approval allows.
- Hybrid Access: AI on SSH servers without an agent: Share saved SSH servers with AI clients through WECOMMANDER on your own computer (Windows, macOS, Linux): nothing installed on the server, keys never leave your computer, approvals and AI permissions apply.