Troubleshooting
Find your problem by what you see on the screen, then follow the steps under it. Most problems with a computer, an install or a task that will not send are fixed by one of three things: opening AgentWitch Local on that computer, updating it, or repairing it. If nothing here helps, the last section tells you how to reach the team.
#Start here
- On the computer that should do the work, open AgentWitch Local, the menu bar app. Its status should say Running.
- In your browser, open Computers. The computer should say Online.
- If either is wrong, find the matching symptom below.
#The computer says Offline or "Computer unreachable"
Cause: AgentWitch cannot reach the computer. The app is closed or stopped, or the computer is asleep or off the internet.
Fix:
- On that computer, open AgentWitch Local. If it says Stopped, choose Start.
- Check the internet connection. The app shows Waiting for internet and reconnects by itself when it is back.
- On the website, choose Retry, or Reconnect computer if that is what the message offers.
AgentWitch Local starts at login only if Open at login is on in its Settings. When it is off, assistants cannot use the computer until you open the app.
If the app stays Stopped, make sure it lives in your Applications folder. An app running from a mounted disk image stops working when the image is ejected. Copy it to Applications, eject every image, and open it again. On a Mac shared by several users, the app runs only for the user who is signed in at the screen.
#The computer says Reconnecting
Cause: The computer was online a moment ago and should reconnect on its own.
Fix: Wait a minute and try again. If it stays that way, open the computer's menu on Computers and choose Restart AgentWitch. If the Mac app says AgentWitch cloud is unreachable and "Nothing is wrong on this computer", the problem is on AgentWitch's side or in the network. Your link is kept, and the computer reconnects by itself when the cloud is back.
#"Update needed" or "Too old to connect"
Cause: AgentWitch Local on the computer is older than the website needs. New tasks are blocked until you update.
Fix: Choose Update AgentWitch Local in the message. Or:
- In the Mac app, open Settings, go to Updates, choose Check for update, then Restart to update.
- On Computers, open the computer's menu and choose Update.
The app also checks once a day. If the update will not apply, follow "Repair this computer" below.
#"This computer is not linked"
Cause: The computer is not connected to your account yet, or it was removed or replaced.
Fix: On Home, choose Connect this computer. In the Mac app, choose Connect this computer and sign in when your browser opens. Then approve in AgentWitch Local to finish. If the Mac app says An account needs you to sign in again, choose Sign in again.
#The install does not finish
The Mac app is built for Apple Silicon Macs (M1 and later). It does not run on a phone or in a browser. On a phone, choose Send the install link to your Mac and open the email on the Mac. Install and connect has the full steps.
Choose Download for Mac, open the file, drag AgentWitch into Applications, and open it from there. If your Mac asks, choose Open. If setup fails, the message says why:
| You see | What to do |
|---|---|
| We couldn't download the AgentWitch app | Check your internet connection, then Retry setup. |
| Your Mac is out of disk space | Free up some space, then Retry setup. |
| Your Mac blocked the install | Allow it when your Mac asks, then retry. |
| Another app is using part of the ports AgentWitch needs | Close the other app, or try again. |
| Something went wrong during setup | Retry setup. If it keeps failing, Repair. |
After two failed tries, Get help opens the repair page.
On Linux, make the AppImage runnable or install the .deb package. A computer that shows "Needs Node 22.13+" needs a newer Node. On Windows there is no installer: AgentWitch runs inside WSL2. Go to Home, choose Connect this computer, and copy the command it shows.
#Sign-in problems
| You see | Cause and fix |
|---|---|
| Account already exists | That email has an account with another sign-in method. Use that method, or the emailed link. |
| Sign-in link not valid | The link expired or was already used. Ask for a new one. |
| Email sign-in unavailable or failed | The email could not be sent. Sign in with Google, or try again later and check the address. |
| Sign-in cancelled | Google sign-in was cancelled. Try again. |
| Agree to continue | Tick the box for the Terms and Privacy policy. |
If the email does not arrive, check spam, then choose Resend when the countdown ends. There is no password sign-up: sign in with the emailed link, then set a password in Account. Too many wrong passwords block password sign-in for that address for 15 minutes. The emailed link and Google still work.
In AgentWitch Local, if it says Signed out, choose Sign in. Your browser opens. When it says you are done, come back to the app.
#An assistant cannot connect
- Claude, ChatGPT or Gemini CLI: in the Members list choose Add, then Add an assistant, then Connect Claude, ChatGPT or Gemini with sign-in. Follow the three steps for your app, then choose Allow (see Connect your assistant). Claude needs a Pro, Max, Team or Enterprise plan. ChatGPT needs developer mode on. If you see "This link expired", start again from the assistant.
- "You can't add assistants to that project": pick a project you own, or ask the owner for Member access. Viewers cannot add assistants.
- Cursor, Codex and others: an invite stops working when it is used up, expires or is cancelled. Make a new one in the same place. A code that expired or was already used needs a new code from the assistant.
- It joined but nothing happens: the owner still has to approve it. Look for a "Wants to join" card in the Members list, or under Needs you on Home.
- A coding tool shows "Sign in needed": open that tool on the computer and sign in again.
- A hosted assistant shows "Wake failed": paste a new wake link in its row.
#Nothing happens after Send
The Send button is disabled, or the task never starts. A message above the button says why:
| You see | Fix |
|---|---|
| Update needed | Update AgentWitch Local (see above). |
| Offline | Open AgentWitch Local on the computer, then choose Retry. |
| Computer unreachable | Check the network, then choose Reconnect computer. |
| Reconnecting or Connecting | Wait a few seconds and retry. |
| New task isn't ready | Choose Fix setup. |
| No coding assistant is ready | Choose Set up a coding assistant, install it, and sign in. |
| Add a task | The task is empty. Write what you want done. |
If the computer is not ready, you can choose Queue for later, or Use online computer if you have another. A queued task sends when the computer connects. If the live view says "Lost connection to your computer", open AgentWitch on it, or send the task again.
If you sent the task to someone else's computer, they must approve it. The request ends after a few minutes and nothing runs, so ask them to approve it or send it again.
"Blocked: that folder isn't this project's folder" means the task ran nowhere. "This project has no folder on this computer yet" means you must set one. Open the project's Health tab, choose Folder, and fix the path, or set it in AgentWitch Local.
#The token check shows nothing
The token check runs on your computer, so the computer must be online and AgentWitch Local must be open. Token check and savings explains the results.
- On Home, find the project and choose Scan token leaks. Until you do, it says Not scanned yet.
- To scan again later, open the project's Health tab, choose Token leaks, then Scan now.
- If it asks for a folder, choose Folder in the same tab, add the project's path on your computer, and scan again.
- If you see "Scan runs on this computer", open the page in a browser on that computer.
- If you see "AgentWitch Local on this computer is out of date", choose Update this computer.
Lean means nothing worth trimming was found.
#Repair this computer
Use this when connecting fails, AgentWitch Local does not answer, or the computer is too old.
- Easiest: in AgentWitch Local, open Settings and choose Repair setup. It reinstalls the app and restarts it. Your projects, folders and settings stay, and running tasks on the Mac stop.
- If the app will not open, go to agentwitch.com/setup/repair-this-computer. Under "Advanced: terminal commands" you get Update, Restart, Reconnect and Check it works, each with a command to copy. Do them in order and stop when the check works.
- Do not share the output of the check. It can include a private link code.
If you still cannot connect, remove the computer and link it again. On Computers, choose Delete from the computer's menu, then Connect this computer. Privacy and trust explains what removal keeps.
#Contact the team
- Send feedback: open the account menu and choose Send feedback. Pick "Something is broken", "Idea or request" or "Other", describe what happened, and choose Send. You must be signed in. If it will not send, write to feedback@agentwitch.com.
- Privacy questions: privacy@agentwitch.com.
- Terms questions: legal@agentwitch.com.
Say which computer you use, what the screen said, and what you tried. If you can, attach the log: in AgentWitch Local, open Settings and choose View logs.
#Query aliases
- computer shows offline in AgentWitch
- AgentWitch update needed
- task will not send to my computer
- AgentWitch sign in link not working
- repair AgentWitch Local on this computer