AgentWitch Docs
Browse docs

Chapter 9 — Troubleshooting

Start here when Send is blocked, the Mac looks wrong in Home, a Run never attaches, or updates fail. This chapter uses user words (Mac, Task, Run, Playbook) and points to deeper System Q&A and open KNOWN_ISSUES entries.

Most fixes are learn from usage in practice: read the honest banner, adjust Mac health or DNS, Run again or Try again on one workflow step—then Save as playbook when you have a stable pattern (four pillars — learn from usage). AgentWitch does not auto-rewrite your Playbooks because a run failed; you stay in control.

Quick wins first, then themed sections for DNS, reconnecting, and bundle update.

A Linux browser can use the Console. Desktop Linux Home shows the host install command. An x86_64 Linux machine can host Tasks. It will not show “This computer” (Q&A). A host started with npm run agent-witch is listed as Linux when it runs on Linux.

Pull into repo on a project writes the linked playbook into .cursor. The folder must be under your home directory.

A run that lacks a writer API key and cannot start the CLI shows Failed — Writer API key missing and Claude CLI can’t run. Completed with fallback means the CLI did run.

#Before you reinstall

Try this order (most issues resolve without a fresh install):

  1. Refresh the Home page or Mac device list (tab focus retries local identity on macOS).
  2. Read the Send banner on New task—it names one primary reason (send readiness codes).
  3. On the Mac, open AgentWitch Local (http://127.0.0.1:43347) → Status / Traffic: is the WebSocket connected?
  4. Retry the Task after ~10–30 seconds (common after console deploys).
  5. Only then: Update local or self-update (see Install bundle update below).

#Mac app missing

If the menu bar app is not installed, open /download on that Mac (Apple Silicon) before you try revive steps below.

#AgentWitch Local not responding

AgentWitch Local listens on a port unique to your account on this computer. It saves that port in ~/.agent-witch/profiles/<account email>/local-app-port.json ("localAppPort"). Older versions used 43347 for everyone; do not assume that port.

Symptoms

  • The health check fails:
    port="$(sed -n 's/.*"localAppPort"[^0-9]*\([0-9][0-9]*\).*/\1/p' "$HOME/.agent-witch"/profiles/*/local-app-port.json | head -n 1)"; curl -sS -m 5 "http://127.0.0.1:${port}/health"
  • The console can still show your Mac online when the background client (AWI) and bridge (AWB) are running without Live bound.

Common mistakes

  • $AW_HOME unset — paths like /agent-witch.error.log mean the variable was empty. Use AW_HOME="$HOME/.agent-witch" (production install) or AW_HOME="$HOME/.local-agent-witch" (localhost dev) before tail or cat.
  • com.agent-witch-live — that LaunchAgent exists only when Live runs as a separate service. Most installs use one com.agent-witch (or com.local-agent-witch) process that includes Live.
  • Literal PORT in wake URLs — read the bridge port from "$AW_HOME/wake-port.json" (often 47892), then curl -X POST "http://127.0.0.1:<port>/watchdog/revive".

Fix

  1. On Home: Status & settings on this computer opens the Mac app (agentwitch-local://status). The Revive AgentWitch Local modal appears when health is down—copy the Terminal block from the modal.
  2. Or run the repair: curl -fsSL https://www.agentwitch.com/install/agent-witch-update.sh | bash. It finds the saved port itself.
  3. Otherwise paste the revive script from the modal, then read "$AW_HOME/agent-witch.error.log" if health stays down after launchctl kickstart.

#Send blocked — read the banner

Banner / reason (typical)MeaningWhat to do
Update neededMac install bundle older than cloud requiresUpdate local
Mac unreachableDNS/network from Mac to www.agentwitch.comDNS / ENOTFOUND
Mac offlineThat device row has no hub socket and no check-in in about 3 minutesAWL Connected but AWC offline
ReconnectingSeen recently, no live socket on this requestReconnecting
Connecting / New task isn’t readyMulti-server relay or handoffWait, refresh devices, retry
Add a taskEmpty prompt / form validationFill composer or workflow form

Mac picker labels (Online, Seen recently, Reconnecting (another server), Offline) describe presence—not always send-ready. You need Online + dispatch-ready for writer Tasks.

Copy reference: AWC Mac reconnecting vs local live.

#Cursor: list_project_tasks returns forbidden

Symptoms

  • MCP or task intake calls list_project_tasks (or create/update/split) and the error is forbidden.
  • Cursor shows both agent-witch (stdio) and a cloud AgentWitch Access server.

Cause

The cloud plugin runs as a bot seat (agt-…@agents.agentwitch.com), not as this Mac’s paired owner. Owner project tasks require device invoke on a paired Mac.

Fix

  1. Use the local agent-witch MCP server (install writes it to ~/.cursor/mcp.json) or Terminal: agent-witch aw list_project_tasks --json '{"projectId":"…","status":"queued","limit":10}'.
  2. Turn off or remove the cloud AgentWitch Access MCP entry in Cursor when you work on this Mac.
  3. Update local to install bundle 425+ so stdio includes task tools; then restart AgentWitch or run Update in the Mac app.

Details: device-scoped agent task tools Q&A.

#DNS — Mac cannot reach agentwitch.com (OPEN-001)

Symptoms

  • Mac error logs under ~/.agent-witch/ show getaddrinfo ENOTFOUND www.agentwitch.com.
  • WebSocket never stays up; console shows offline or seen recently only.
  • Send may show Mac unreachable when that signal is surfaced.

Cause

Client or network DNS, firewall, or VPN—not something you fix by editing wsUrl on production installs (bundle 103+ uses the hardcoded production WebSocket).

Fix

  1. On the computer, verify resolution: dig www.agentwitch.com or nslookup www.agentwitch.com.
  2. Fix VPN, corporate DNS, or firewall blocking outbound HTTPS/WSS.
  3. Ensure install bundle 103+ (self-update if older).

Deep dive

  • AgentWitch KNOWN_ISSUES — OPEN-001
  • Repository hosting — production WebSocket

Do not point a production Mac at CHECK24 URLs unless your organization explicitly deploys there.

#Mac “reconnecting” after deploy or multi-server (OPEN-002)

Symptoms

  • Message like: The selected computer is reconnecting. Your task will send when it checks in.
  • AgentWitch Local or local bridge looks fine, but New task still blocks Send.
  • Picker shows Reconnecting (another server) or Seen recently.

Cause

Two different “live” signals:

  • Local bridge / AWL up → proves browser is on the computer and AWI may be running.
  • Console hub → needs a live WebSocket on the server handling your dispatch (multi-replica deploys and load balancers can briefly miss).

After a production deploy, sockets drop for a few seconds even when AWI reconnects quickly.

Fix

  1. Wait for AWI to reconnect (Status → Traffic: agent.register).
  2. Refresh Home / Mac list; retry New task (client retries on mac_reconnecting where applicable).
  3. Keep install bundle 103+.
  4. Operators: sticky routing on hub cookie aw_hub_instance (see ADR 0005)—not end-user config.

Deep dive

  • AWC Mac reconnecting vs local live
  • KNOWN_ISSUES OPEN-002

Not the same bug: Update local broke LaunchAgent—cloud shows reconnecting because AWI never loaded.

#Install bundle update (stale or blocked Send) (OPEN-003)

Symptoms

  • Update needed on composer; Update agent CTA.
  • Home Mac detail shows bundle version behind cloud.
  • Old client bugs persist until update completes.

Cause

Self-update runs on heartbeat, hourly updater, or when you trigger Update local via bridge. Network or wake API failures can delay it. Prompt optimizer in Live is part of that install. An optimizer change reaches the computer only after the console advertises a newer bundle version and the computer updates.

Fix

  1. In console: Update agent / Mac row menu → Update local (same computer as browser).
  2. On Mac terminal (optional): npm run agent-witch:self-update from a dev checkout, or use AWL Update.
  3. Compare ~/.agent-witch/install-version.json with GET /install/agent-witch/version on the console origin.

Deep dive

  • KNOWN_ISSUES OPEN-003
  • Send readiness — update_needed
  • Mac devices UI: KNOWN_ISSUES (Update local menu)

#Update local stuck reconnecting (AGENT-067)

Symptoms

  • After Update local, console stays on Mac reconnecting (presenceTier: recent).
  • Default bridge :47892 down; wake.sh / LaunchAgent will not load.

Cause

Invalid com.agent-witch.plist (install script once embedded bash inside XML). launchctl bootstrap rejected the agent.

Fix

  1. Install bundle 125+ (self-update or restart AWI)—client rewrites invalid plist on start, AWL Update, and heartbeat update.
  2. If identity unlinked: run Connect this computer from Home while signed in.
  3. AWL posts update to runtime wake port from wake-port.json when present.

Deep dive

  • Q&A: Update local and LaunchAgent plist
  • KNOWN_ISSUES AGENT-067 / OPEN-003 context

#“This computer” / Connect this computer confusion

UIMeaning
Connect this computer rowLink the computer where you opened the browser
This computer badgeCloud device hash matches local bridge /identity
Mac offlineThat paired row has no live socket and has not checked in lately. AWL Connected can still be a different device or origin.

If no row says This computer, use Connect this computer in the hero or under Your Devices. That links the computer you are using now. The button stays hidden only after this browser’s pairing token already matches a listed device. Mac settings & connect only opens Your setup. When a row is already This computer and Offline, start AgentWitch on that computer. Click the offline row for wake steps.

If This computer sits on an Offline Your computer while another named computer shows Online, the badge is on a stale claim (HOME-061)—not proof that the live helper is down. Refresh Home after the Console fix; you can also remove the unused Offline row.

Clicking Connect this computer more than once does not add another computer. Home keeps the latest unused link and drops the extras (rows named Your computer or Computer 2 with Version unknown). Reload Home if those extras are still listed. A computer with a real name, such as a serial or hostname, stays.

If AgentWitch is already open on this computer, the click does not restart it. Paste the command to relink. After you remove that Mac in the Console, a current install stops and deletes the connection and the app code. Projects, reports, runs, and Ollama remain, so Connect this computer can link the computer again. Update local does not. An install from before that behavior only disconnects until it updates. See Deleting a Mac.

If you do not see This computer on macOS: bridge not running, wrong port, or signed-out page (no probe). Not a DNS issue by itself.

Why there is no Connect button when devices are offline.

How AWC knows this computer · AWB localhost identity.

#Run stuck on Connecting / empty terminal

  1. Confirm the Mac is Online for send—not only “seen recently.”
  2. Live Run honesty: Connecting until log attaches, then In progress (run UX honesty).
  3. Check Reports / run detail for reconnect hints if dashboard WebSocket dropped (reports KNOWN_ISSUES — reconnect copy themes).
  4. Spawn failures on computer (PTY): update install bundle; see agent feature KNOWN_ISSUES if terminal never streams.

#Workflow checkpoint or retry issues

  • Paused at human step: look for top banner after Not now; open checkpoint sheet and Continue.
  • Failed agent step: use Try again on the same step—do not restart the whole workflow unless you intend to.

Official workflow checkpoints and retry · Chapter 6.

#Library / playbook issues

  • Guest drafts only on one browser until sign-in sync: Guest library drafts.
  • Send disabled on library workflow: connect Mac or Cursor Cloud key (Chapter 7).

#Project folder wrong or missing

Console cannot pick Mac folders remotely. Use AgentWitch Local or local folder picker.

AWC project folder picker · AWC vs AWL projects.

#Local dev vs production (support checklist)

CheckProduction userLocal developer
Originhttps://www.agentwitch.comhttp://localhost:3000
Mac config dir~/.agent-witchOften ~/.local-agent-witch
Bridge port4789247893

Local bridge doc · AWL loopback origin.

#Mac Knowledge page empty or search returns nothing

Symptoms

  • AgentWitch on this computer → Knowledge shows no chunks after successful Runs on a linked project folder, or search always returns empty.

Checks

  1. Project folder is set for the repo (Chapter 4)—knowledge is keyed to that folder on the computer, not the Console alone.
  2. Finished Runs with exit code success index snippets; failed runs use a separate error path (see Local knowledge).
  3. Embeddings use a local Ollama API on the computer (http://127.0.0.1:11434 by default). If Ollama is not running, indexing and search may no-op without blocking Send.

Developers: AGENT_WITCH_OLLAMA_URL / AGENT_WITCH_EMBED_MODEL — developer guide ch.10.

#Where to search next

NeedLocation
Short “how it works” answersdocs/qa/README.md
Prompt optimizer sample and historyprompt-sdlc.md — instructions at http://127.0.0.1:43347/prompt-optimizer/guide; history shows a short title, Delete removes a run, the pass score fades across the score colors, and the form stays filled and locked while a run is working, and a manual score and its reason are shown to the improver. The run stops when the score reaches the pass score, you press Finish, the round limit is hit, or the score has not risen for 3 rounds. Finish counts the run as complete. After each scored round the page shows the tokens spent so far. The round limit starts at 10. The next rewrite always starts from the highest scoring prompt. Reasons from lower scores become an avoid list. After 3 tries that do not beat the best, the run stops and those reasons are included. Click a step for that step’s score, feedback, and saved prompt. When the run finishes, After a folder is chosen, a skill list can fill the prompt. Save as a skill uses that skill’s name, description, and file name, and asks before replacing an existing file. A bot on this computer calls http://127.0.0.1:43347/prompt-optimizer/agent and runs the writers in the project folder
Open Mac bridge / dispatch riskssrc/features/agent-witch/KNOWN_ISSUES.md
Mac Home / Update local UImacDevices KNOWN_ISSUES
Trust and boundariesChapter 8 — Production and trust
First-time setupChapter 1 — Getting started · Chapter 4 — Mac connect
AI registration / Agent Mailai-self-registration-webmcp.md — method none works without a mailbox; agentmail returns 503 when the server key is missing. rate_limited or busy means wait; do not retry in a loop. Call get_agent_guide for the current tool list

Indexed search (agents and power users):

npm run feature-knowledge:query -- "Mac reconnecting DNS update bundle" --feature=docs

#Query aliases

  • AgentWitch troubleshooting Mac offline reconnecting
  • Send blocked update needed DNS ENOTFOUND
  • install bundle mismatch update local LaunchAgent
  • workflow retry checkpoint not now banner
  • this computer identity connect bridge 47892
  • sua loi AgentWitch Mac reconnecting
  • khong gui duoc task vi Mac offline
  • Linux cannot access AgentWitch, Linux host vs Mac app
  • loi DNS www.agentwitch.com tren Mac
  • cap nhat bundle AgentWitch update needed
  • sau update local van reconnecting plist
  • hoc tu loi troubleshooting, run lai sau khi sua loi Mac
  • bon tru cot learn from usage sua loi agent