Troubleshooting

Symptoms below, in order — search the page for yours. Os { NotFound } from herdr plugin · update says "not currently on a branch" · tailscale serve failed · isn't answering (service won't start) · phone can't open the URL · page loads but stays empty (blank page, 403) · a password prompt won't take your reply · no push notifications · gone after a reboot · a pane is stuck narrow · Collie refuses to open a tmux window · tmux list: output did not parse · herdr plugin list shows the old version · stale UI after a rebuild · I saved a machine in Herdr and the phone does not show it · an update started from the phone stays at staging · a phone update on macOS leaves Collie unloaded · on macOS, collie status says "loaded, not running" · a pane shows no prompt-cache chip · a Kiro pane's History opens empty · a pane has no Chat or History · a new Codex pane says it has no history yet · the phone says Collie cannot read a screen the agent is not showing · sending failed 3 times and the phone offers a report · an agent is greyed out on the New page · Start says there is no folder, or says it could not confirm · walky talky: send is refused, "run this inside a pane" · walky talky: the message sits in the inbox and was not typed · walky talky: "no log record on this machine" · walky talky: the skill is stale · a durable agent does not show up, or says Unreachable.

herdr plugin … fails with Error: Os { code: 2, kind: NotFound, message: "No such file or directory" } (plugin install fails, action invoke fails). This is not a Collie problem — it means the Herdr server isn't running, so its CLI can't reach the control socket (~/.config/herdr/herdr.sock). The tell is the raw Os {…} error: a reachable server answers path/manifest problems with structured JSON (e.g. plugin_manifest_not_found), so a bare Os { NotFound } is a failed socket connect, before Collie or your path is ever examined. It hits link, install, action invoke — every subcommand that talks to the server — while herdr plugin --help still works (it never opens the socket). Fix: start Herdr first (herdr server &, or just launch the Herdr TUI — it boots the server), confirm ls ~/.config/herdr/herdr.sock now exists, then retry the install. herdr plugin list is a quick probe: if it throws the same error, the server is down.

update fails with You are not currently on a branch. A GitHub install made before 0.23.1 (#63) — herdr plugin install detaches instead of cloning, so the old update had no branch to git pull into. The fix ships inside the checkout it repairs, so it takes one reinstall to land: If that fails with "You are not currently on a branch" has the three commands.

start prints note: tailscale serve failed. Collie itself is fine (still up on 127.0.0.1) — only the tailnet ingress didn't come up, and tailscale's own error is on the terminal above the note. Usual causes: your user isn't the Tailscale operator (sudo tailscale set --operator=$USER), the node is logged out (tailscale up), or — on Headscale / .internal tailnet domains — HTTPS certs aren't available, which is exactly what COLLIE_SERVE_MODE=http is for: set it in .env, then bin/collie restart. Verify with tailscale serve status.

serve says HTTPS certificates are not enabled on this tailnet. Nothing was published, and nothing is waiting. Open the admin console, turn on "Enable HTTPS", then run collie serve again. On Headscale / .internal domains there are no certificates to enable; use COLLIE_SERVE_MODE=http instead.

Banner shows ⚠ Collie isn't answering on :8787 yet (service won't start, connection refused). The service was started but the HTTP server isn't answering the probe. Check the unit first — systemctl --user status collie — then bin/collie logs (or journalctl --user -u collie -f to watch live) for why: most commonly the port is already taken (set COLLIE_PORT in .env, then bin/collie restart, which also re-runs tailscale serve against the new port) or the first build failed (the log says so; fix and run bin/collie build). The unit auto-restarts every 5 s, so once the cause is fixed it usually comes back on its own.

Phone can't open the tailnet URL. Work down the list: (1) the phone runs the Tailscale app and is connected to the same tailnet as the host; (2) you're opening the banner's tailnet URL (bin/collie url), not the local one — http://127.0.0.1:8787 only works on the host itself; (3) MagicDNS is enabled in your tailnet's DNS settings (the URL is a MagicDNS name); (4) the host is online — check tailscale status on the host, or ping the host from the phone's Tailscale app; (5) your tailnet policy actually admits a peer to this node — if it doesn't, the banner now says so under the tailnet line, and nothing else will: the front door is published correctly, the cert is valid, and curl from the host itself returns 200, because loopback never touches the packet filter. Two things make this one especially misleading — tailscale ping succeeds (disco pings bypass ACLs), and blocked traffic is dropped rather than refused, so the phone just hangs and reads as "server down". Fix it in your ACL policy (<https://login.tailscale.com/admin/acls> on Tailscale; your policy file on Headscale). The check is best-effort and deliberately unsure of itself: it speaks up only when this node's filter admits nothing — which can equally mean no other device has joined the tailnet yet — and stays quiet whenever it can't tell.

Page loads but stays empty (blank page, white screen); API calls fail 403 cross-origin rejected. You're reaching Collie through an origin it doesn't expect — a custom domain, or a proxy that rewrites Host. Allow the exact public origin with COLLIE_ALLOWED_ORIGINS (see Configure), or make the proxy forward Host unchanged — the fourth proxy requirement in docs/deployment.md.

A sudo (or SSH passphrase, or gpg) prompt won't take your reply. Use Type in the actions row above the keyboard, not Send. Send verifies what it typed by reading it back off the screen before it presses Enter (#34), and a password prompt turns echo off, so there is nothing to read back — Type sends your keystrokes straight to the pane, Enter included. Nothing you type in Type is stored, echoed into a draft, or restored later, and the moment Collie recognises a password prompt it drops the stored draft too (#103).

No push notifications arriving. Fire one by hand: bin/collie push-test. Three causes, in the order the command distinguishes them: push says it's disabled (the keys never reached the bridge — run push-keys and restart, see Web Push); it says there are no subscribed devices (this phone never enabled them in Settings → Alerts); or it reports a send and nothing arrives (the phone is on a plain-HTTP origin, which is not a secure context — Settings flags it insecure).

Collie is gone after a reboot. On Linux this is almost always lingering, so run loginctl enable-linger $USER (Surviving reboots). On macOS the launchd agent starts at login, so check you're actually logged in (not sitting at the login window) and that the agent is loaded: launchctl print gui/$(id -u)/herdr.collie.

A pane's terminal is stuck narrow, and a full-screen app inside it is squashed (Copilot CLI, top, any TUI drawn into a strip while the rest of the mirror stays blank). The pane's terminal is that narrow, and Collie mirrors it faithfully. A Herdr pane's width comes from its rectangle in the tab's split grid, so a pane sharing a tab gets a share of the columns. Herdr applies pane geometry only while a desktop client is attached (herdr#1709): with nothing attached, closing a split leaves the survivor stuck at the old narrow width, and pane.zoom and pane.resize over the socket do not move it either. Collie cannot fix this from its side; it does not write pane geometry at all (ADR 0031: the phone moves the operator's terminal only on the Show in terminal tap). Nothing about it is app-specific: top in a 54-column pane looks identical. To measure it, run tput cols in the pane. That is the real width, and it can disagree with what herdr pane layout reports. To fix it, attach a Herdr client, then zoom or resize the pane there (herdr pane zoom <pane-id> --on moves the terminal once something is attached), or close the pane and open a new one (#167).

Collie refuses to open a tmux window (the phone's new tab comes back declining, naming window-size). Not a fault in the request: on tmux below 3.7, spawning a window while the server's window-size is manual crashes the whole server (tmux #4849, fixed in 3.7), and a crashed server takes every window with it. Collie declines instead, and names the tmux it saw. The fix is the line it prints — tmux set -g window-size latest on that server — or tmux 3.7. Nothing else is affected: every other action on those panes keeps working (Requirements carries the same caveat).

Collie logs tmux list: output did not parse and the dashboard reads empty. Not a crash: some tmux versions (3.4, not 3.6b) escape the separator this adapter reads on their way out of a -F listing. Collie reads both shapes now, so a listing that parses to zero rows is reported as a mux error instead of being stored as an empty herd — the error line names the tmux version and how many lines it saw. A second cause was the locale: started with no UTF-8 locale (a minimal container, a systemd unit), tmux replaces that separator with _ instead of escaping it. Collie now runs every tmux command with -u, so the listing no longer depends on LANG or LC_ALL. If you still hit this, note the tmux -V version and open an issue; the fix belongs in the adapter, not in your .env.

herdr plugin list shows the old version after an update. Expected — Herdr caches the manifest it read at install or link time. The authority on what's running is the footer build stamp, or bin/collie version. For a linked clone update re-links and that self-heals (force it with herdr plugin link "$(pwd)"); on Herdr ≥0.8.0 the manifest is re-read from disk anyway.

Phone shows a stale UI after a rebuild. A PWA's service-worker cache is per-origin, so reaching Collie at two origins (a custom domain and the raw host:8787) gives you two installs, each caching its own bundle. The footer build stamp (vX.Y.Z · sha · time) shows the bundle you're running; Collie reports what it serves via the X-Collie-Build header and /api/config. On a mismatch, the footer offers "new build — tap to update." Otherwise reopen the PWA a couple times (the SW auto-updates) or clear that origin's site data. Best practice: pick one HTTPS origin and stick to it. (Over plain HTTP the SW can't register — always fresh, but no PWA features.)

I saved a machine in Herdr and the phone does not show it. Expected. Herdr's saved machines are its own client's list, and a crew is Collie's own; neither list feeds the other. To reach that machine from the phone, enrol it: collie crew add <ssh-host> on the lead, then collie restart on the lead and collie crew status to check the link. Adding or removing a machine in Herdr changes nothing in the crew (Herdr machines and the crew).

A pane shows no prompt-cache chip. One of three things, and collie doctor tells them apart. The pane's harness has no journal adapter, which its integration-<agent> and journal-roots lines name. The pane never reported a session, which its agent-sessions line lists by pane id. Or the agent has not taken a turn yet, which is not a fault: nothing is shown before it is measured, so the chip appears on the agent's first reply. A harness whose vendor publishes no cache lifetime shows nothing either, and cache-claims lists every rule this build does ship.

A Kiro pane's History opens empty. Check that the pane's Kiro holds a session lock:

cat ~/.kiro/sessions/*/*/.lock

Herdr names no session for a Kiro pane, so Collie finds it by the lock the running Kiro holds. That works only on Herdr, the one multiplexer that lists a pane's foreground processes, and only when exactly one Kiro process runs there. Otherwise History says the pane has no agent session.

Collie reads Kiro V3 sessions, started with --v3 or --agent-engine v3, or with V3 set as the engine in Kiro's own settings, so start Kiro again that way in that pane. Kiro has no Herdr hook to install. If its sessions live somewhere else, set kiro_root, then run collie restart.

A pane shows the terminal where you expected Chat. Chat is the default for an agent pane, so one of two things holds. This device chose the terminal earlier: open the pane's ⋮ menu and tap Chat view. Or the pane has no session or no log to read. A new pane shows Chat with "Send a message to start" and falls back to the terminal when its first turn ends with nothing to read, or when it asks a question first; the menu row says which part is missing, and the next entry has the steps.

A pane has no Chat or History, and the ⋮ menu says the pane named no session. Chat and History read the agent's session log, and Collie finds the log only when the agent reports its session through the multiplexer. On Herdr that report comes from the agent's own integration, so a missing or old one hides both with no other symptom. collie doctor names the pane under agent-sessions and the fix under integration-<agent>.

1. 01
   Run herdr integration status. If the agent is not installed or outdated, run herdr integration install <agent>. Oh My Pi is omp, and pi is pi: each needs its own.
2. 02
   Restart the agent in that pane. An agent loads its hook when it starts, so one that was running during the install keeps reporting nothing.
3. 03
   If the hook is current and a restarted pane still reports nothing, check whether the agent was started from a shell that another agent opened. Oh My Pi's hook stays silent when OMPCODE=1 is inherited from the parent agent. Start it from a fresh terminal.

On tmux, zellij and tern only Claude Code reports a session, through Collie's beacon hooks. Run collie hooks install claude (Collie writes hooks into Claude's own settings). The other agents have no Chat or History there.

A new Codex pane says it has no history yet. Expected until its first turn. Codex reports its session to Herdr only when the first prompt is sent, not when it starts, so a fresh pane has no session, and no History link, until then. collie doctor lists such a pane under agent-sessions as not reported yet, and does not count it as a fault. If the note is still there after Codex has replied, open /hooks in Codex. When its hooks change, Codex asks you to review them, and "Continue without trusting" turns the Herdr hook off while herdr integration status still says it is current. Trust the hook there, or run herdr integration install codex and start a new session.

The phone says Collie cannot read a dialog, or a send does not reach the input box, while the agent at the desk shows its normal prompt. Collie misread the screen, usually because the agent changed how it draws it. Please open an issue with the screen's raw text, which shows what a screenshot cannot (the colours and dim text Collie reads). Find the pane id with herdr pane list, then run

herdr pane read <pane-id> --source recent --lines 200 --format ansi > pane.txt

while the phone still shows the problem, and attach pane.txt together with the agent's version (claude --version, codex --version, and so on). The file is the terminal's text, so read it first and remove anything private.

Sending failed 3 times and the phone offers a report. Three sends in a row on one pane failed for a reason that points at Collie: it could not read or write the input box, the text went in and Enter did not follow, or it lost track of the send. A refusal that protects you (a draft in the box, a running turn, an open dialog) does not count. Tap Report on the card. The sheet shows the whole issue before anything leaves: the Collie and agent versions, the multiplexer, and each failed send's codes. It holds no text you typed and no screen unless you turn on Include what I typed or Include the screen. The screen is the pane's last 40 rows with known secret shapes masked; read it anyway, because the issue is public. Open on GitHub opens the filled-in form in your browser, under your own GitHub account, and Copy report copies the same text. Tap Already reported? first to find an issue with the same signature line. The pane menu and Settings → System open the same sheet at any time. The cross closes the card on that pane until a send works again. A crew member's pane does not offer a report yet; use the steps above.

An update started from the phone stays at staging. On Collie up to 1.6.0, an update tapped on the phone could stage the new version and then stop: the runner that performs the swap was never started, the service kept serving the old version, and the run record sat at staging with the lock held. The tell is three facts together: collie update --status reports staging (or, past ten minutes, interrupted — the updater is gone), the version directory for the new release exists under versions/, and the runner log at ~/.config/collie/collie.log is 0 bytes. A collie update typed at a shell on the same machine always worked, which is the same defect seen from the other side. It is fixed from the next release on: the handoff now waits for the user manager to confirm the runner, and a handoff that was refused is reported as a failure with the manager's own reason.

To clear a machine that is already stuck, do nothing for ten minutes: a run whose updater is gone stops blocking a retry ten minutes after its last transition, and the next tap proceeds. To clear it now, delete the record, the lock and the staging progress file, then check what --status says:

collie update --status            # note the pid it names
ps -p <pid> -o command=           # empty output: the updater really is gone
rm -f ~/.local/state/collie/update.json ~/.local/state/collie/update.lock
rm -f ~/.local/state/collie/update-staging-*.log
collie update --status            # "no update has run on this install yet"

There is no verb that clears a stale run, and these three files are the whole of the state a stalled staging leaves behind. A suffixed instance keeps them in ~/.local/state/collie-<name>/ instead. Never delete these while an update is actually running, and check the pid first: a live updater whose lock you removed will flip current with nothing guarding it. Leave versions/ alone. The half-staged version directory is harmless, the retry builds into it again, and the retention sweep removes what it no longer needs.

A phone update on macOS leaves Collie unloaded. Run this on the Mac:

collie restart

On Collie up to 1.8.x, an update tapped on the phone could stop the launchd agent and never load it again, so the phone lost the service and launchctl print gui/$(id -u)/herdr.collie found nothing. The runner shared the agent's process group, and restarting the agent killed it half way. collie restart writes the agent's plist again and loads it. From 1.9.0 on, the bridge starts the runner in a process session of its own. If a phone update still unloads the agent after that, run the same command and add a note to #213.

On macOS, collie start finishes but collie status says "loaded, not running". The launchd job is loaded and no process runs, so the log is empty. Start the job by hand:

launchctl kickstart gui/$(id -u)/herdr.collie
collie status

A suffixed instance has its own label, for example herdr.collie-next. From 1.17.0 on, collie start and collie restart do this step for you and print a warning with this command when no process shows up. If the job stays "loaded, not running" after that, read the log with collie logs, then add a note to #213.

An agent is greyed out on the New page. The reason follows its name in brackets. "not installed" means the machine did not find the agent's command on the PATH your login shell uses. In a login shell on that machine, run bash -lc 'command -v claude' (or the agent's own name). If it prints nothing, install the agent there, or fix the line in your shell's login file that adds it to the PATH, and reopen the page. On a crew, check the machine you picked: each member looks on its own disk. "this machine runs an older Collie" means update that member (Starting something on a machine). "needs Herdr" and "only on" a machine's name belong to the New worktree switch, not to an agent.

Start says "There is no folder … on this machine", or "could not confirm the start". The first means the folder is not on the machine that runs the start, so nothing started. A name with no leading / or ~ is a folder under your home, so projects means ~/projects. Create the folder, or pick one from Recent. The second means the phone lost the reply. Look at the dashboard first, because the pane may exist. Try again sends the same request and never opens a second pane (Start an agent or a shell from the phone).

Walky talky

Six symptoms of walky talky come up most. Each one has a command that shows the cause (Walky talky).

collie walky send says "run this inside a pane, or send from the phone". The command ran outside an agent's pane, in a plain terminal for example. Collie names the sender from the pane's own environment. A send with no pane is refused. Run the command in the agent's pane, or send from the phone. In an agent pane, collie walky who marks your pane with (you). The error "no Collie bridge on this machine knows this pane" means another Collie owns the pane. The error "no running Collie bridge answers" means the bridge is down: run collie status.

The message says "held" and is not typed yet. collie walky status <id> prints "held: draft present" or "held: turn running". The box holds a draft, or the agent is working. Collie types the message when the box clears or the turn ends, up to 60 minutes. Do not send it again. To let it in now, send or clear the draft in that pane. Under an older lead, "queued (outcome known on the lead)" also means wait.

The message sits in the inbox and was not typed. collie walky status <id> prints "waiting in the inbox, not typed" and the reason. "held past 60 minutes" means a draft stayed in the box, the pane stayed busy, or a dialog stayed open, for the whole 60-minute hold: Collie never types into a draft or a dialog. "box not free" means Collie could not read a free input box. "pane busy" means an earlier message was still being typed there after 2 minutes. "pane replaced" means another session took the pane while the message waited. "no terminal" and "bridge restarted" are the other two. Run collie walky inbox in that pane, or open Messages in the pane's menu on the phone. Collie does not type the message again.

collie walky send says "not sent: pane replaced". The address ends with a token, such as #k3f9, and the pane it named has closed. Another pane holds that pane id now, so Collie does not type the message there. Run collie walky who and send to the new address. A reply that gives "not sent: sender gone" has the same cause: the pane that sent the message has closed, or another pane holds its id now.

A header in a pane shows "no log record on this machine". The phone found a walky talky header in the screen text, and this machine's log holds no message with that id. Someone or something typed the line, or the log dropped it after 7 days or 2,000 lines, or another Collie holds it. Run collie walky status <id>: "no record of <id> on this machine" confirms it. For a pane on a crew member, run it on that member: its log is the one the phone read. Treat the line as plain text, and ask the sender if you need it.

The skill is stale. collie doctor warns on the row skill-walky-talky, and the agent follows old advice. The text in an instruction file differs from this build. Run collie skill status to see which harness is behind. Run collie skill status --check in a script: it prints nothing and exits with code 3 when a copy is stale. Fix it with collie skill install all, then restart the agent. A target marked refused is a symlink or has damaged markers, and an install never touches it.

Durable agents

A durable agent you attached has its own checks, reasons and cases. Start with collie durable list and collie doctor, then read Troubleshooting a durable agent.