Running itTroubleshooting
Troubleshooting
What to check when an agent shows as unknown, pairing fails, pushes do not arrive, the worker will not start, and other symptoms, each with its cause.
Symptoms and their causes, for whoever administers the computer. Start with these three commands; most answers below come from one of them.
vendetta notify status # is the worker running, and each plugin's state
vendetta config check # does the config parse
vendetta snapshot # every agent as JSON, with where its state came fromThe worker and its plugins log to ~/.local/state/vendetta/notifications/worker.log, which each vendetta notify start empties. Under systemd they log to the journal: journalctl --user -u vendetta-notify.service.
Agents
Section titled “Agents”An agent shows as unknown
Section titled “An agent shows as unknown”Its integrationIntegration. The small piece Vendetta installs into a provider (hooks, an extension, Claude's Mod) so the agent reports its state. is not loaded. An agent without one is still found and titled, but reports no state and takes no remote input. vendetta snapshot shows "source": "process" for it.
| Provider | Fix |
|---|---|
| Claude Code | vendetta install-claude, then restart Claude and resume. It needs Claude Code 2.1.296 or newer; install.sh skips an older one with a note. |
| Codex | vendetta install-hooks, then trust the hooks under /hooks in Codex. Without hooks, Codex state falls back to its rollout files. |
| omp | vendetta install-omp, then restart omp and resume. /reload does not reload extensions. |
| OpenCode | vendetta install-opencode, then restart OpenCode. |
| Gemini CLI | vendetta install-gemini, then restart Gemini and review /hooks. Its settings file must be strict JSON. |
| Aider | Start it with vendetta-aider instead of aider. Versions other than 0.86.2 run unobserved with a warning. |
Agents that were running when you installed need a restart to load the integration.
omp or OpenCode reports no state on macOS
Section titled “omp or OpenCode reports no state on macOS”Their integrations read /proc, which macOS does not have. Those agents are listed and report no state there. Claude Code, Codex, Gemini CLI, and Aider report state on macOS.
An OpenCode pane shows as a process only
Section titled “An OpenCode pane shows as a process only”It runs opencode attach. The plugin runs in the OpenCode server, so the attached pane has no state of its own.
A Gemini agent keeps its old state after you interrupt it
Section titled “A Gemini agent keeps its old state after you interrupt it”Gemini has no cancel or error hook. The state corrects itself at its next event.
An agent is not listed
Section titled “An agent is not listed”- It runs inside a tmux server other than the one Vendetta serves. The worker serves one: tmux’s default, or
[plugins.host-tmux] socket. - Its environment names another Vendetta state directory (
XDG_STATE_HOMEorHOME).
An agent refuses a message
Section titled “An agent refuses a message”| Cause | What to do |
|---|---|
| A question or an approval is open | Answer it first. While a permission dialog is open the agent takes no remote input. |
| Its state is unknown | Load its integration, above |
| Codex, Gemini CLI, or Aider outside tmux and Kitty | Their prompts are typed into a terminal, so they need a host. See Terminals. |
| It runs in a project machine whose link is down | It shows as unreachable and refuses input until the link is back. Nothing is queued. |
A refused message is never sent again for you. In the apps, Resend sends it as a new message.
A message reads “Offline. Not sent.” or “Not confirmed”
Section titled “A message reads “Offline. Not sent.” or “Not confirmed””The device lost its connection. Retry sends it again. One that reads “Not confirmed” may have arrived: check the chat before sending again.
The worker
Section titled “The worker”A command says the worker is not running
Section titled “A command says the worker is not running”The Vendetta worker is not running; start it with `vendetta notify start`The chooser, the apps, and every plugin get their agents from the worker. Start it, or see Run at login.
The worker will not start
Section titled “The worker will not start”| What you see | Cause |
|---|---|
| “Notification worker is already running” | One already holds the lock. vendetta notify status shows it. |
| “XDG_RUNTIME_DIR is required for the control socket” | On Linux the control socket lives under XDG_RUNTIME_DIR, and this shell has none. Start the worker from a login session or a systemd user unit. |
| The config is refused | vendetta config check says what is wrong, such as a bad plugin name, an empty command, no command for a plugin Vendetta does not ship, or two enabled plugins with the same role. |
| It stops and comes straight back, or will not stay stopped | A systemd unit or launchd runs it. Stop it there. |
A config change did nothing
Section titled “A config change did nothing”A file with an error changes nothing: the worker keeps the last good config, logs the error, and sends you an alert. Run vendetta config check. After changing a credential, restart the worker.
A plugin is stuck
Section titled “A plugin is stuck”vendetta notify status shows each plugin’s state.
| State | Cause |
|---|---|
starting |
It has not reported yet. For a plugin of your own: it never called report_health, or a wrapper forked it instead of using exec. |
unavailable |
It exited and waits to restart, could not start, or reported this itself. The log says why. The shortcuts plugin is unavailable on Linux while no Hyprland runs. |
Pairing and the apps
Section titled “Pairing and the apps”Pairing fails
Section titled “Pairing fails”| Message | Cause |
|---|---|
| “The pairing code expired” | A code lasts 10 minutes. Run vendetta app pair again. |
| “Invalid pairing code” | A wrong code. Five wrong tries discard the pending code; make a new one. |
| “No pairing is pending” | The code was already used, discarded, or never made on this computer. A code works once. |
| “App device limit reached; revoke a device first” | 16 devices are paired. vendetta app devices, then vendetta app revoke ID. |
| “That isn’t a Vendetta pairing code.” | What you pasted is not a code or a pairing link |
| Nothing connects | The device cannot reach public_url. Check that the port is served and that the device is on your tailnet or behind your proxy. See Publish. |
For a person’s device, the code comes from their Vendetta: vendetta instance pair NAME.
The address shows no web client
Section titled “The address shows no web client”install.sh builds the web client only when Bun and wasm-bindgen are installed, and says “skipping the web client” otherwise. Install them and rerun install.sh. The iPhone app and the bots work without it.
Voice mode is missing, or voice notes are refused
Section titled “Voice mode is missing, or voice notes are refused”Voice needs [plugins.speech.transcription]. Without it the apps hide voice mode and say “Voice is off: Vendetta has no transcription set up.” On Linux, recordings that are not 16-bit mono WAV also need ffmpeg. See Voice.
The apps open on the chat list, with no overview
Section titled “The apps open on the chat list, with no overview”[plugins.dashboard] is off, or the device is in Simple.
Notifications
Section titled “Notifications”No push on the iPhone
Section titled “No push on the iPhone”[plugins.app.apns]is not set up, or its key belongs to another team than the one that signed the app, as with the TestFlight build. See The iPhone app.curlon the computer has no HTTP/2.- Notifications are off for the app in iOS. Settings in the app shows Enable Notifications or Enable in Settings.
- The chat is muted. A muted chat pushes only its agent’s alerts, and agents a manager starts begin muted.
- The app is in the foreground on that device, which shows the message instead.
No Live Activity
Section titled “No Live Activity”Live Activities need the same APNs setup. The app’s Settings → Notifications says which it is: “Vendetta on your computer can’t show Live Activities: it needs APNs set up.”, or Allow in iOS Settings when iOS has them off.
No push in a browser
Section titled “No push in a browser”Turn on Push notifications in the web client’s Settings, in that browser. Desktop notifications, a separate switch, show only while its tab is open in the background. [plugins.app.web_push] enabled = false turns pushes off for every browser.
No ntfy alert
Section titled “No ntfy alert”vendetta notify testIt fails when ntfy does. Check the topic’s URL and token. Alerts expire after 60 seconds, are tried three times, and are not replayed after downtime. A self-hosted ntfy server needs upstream-base-url: "https://ntfy.sh" for timely iPhone delivery.
No desktop notification
Section titled “No desktop notification”[notifications] desktop is false by default. On Linux it also needs notify-send, a notification daemon, and a worker started from your graphical session so it reaches D-Bus.
Terminal
Section titled “Terminal”Alt s does nothing in tmux
Section titled “Alt s does nothing in tmux”- No key is bound until
[plugins.host-tmux.keys]names it. Check withtmux list-keys -T root M-s, and the worker’s log for the keys table. - The config has no
[plugins.host-tmux]. - You are in a tmux server other than the one the worker serves. A chooser started there says so.
- With tmux inside Kitty under a non-Latin keyboard layout, add the mappings from
integrations/kitty.conf.
Text like ?62;22c appears in a pane over SSH
Section titled “Text like ?62;22c appears in a pane over SSH”Over a slow connection the terminal’s replies to tmux arrive in pieces, and a very short escape-time makes tmux type them into the pane. Set set -sg escape-time 50.
A desktop-wide key does nothing
Section titled “A desktop-wide key does nothing”vendetta notify status shows the shortcuts plugin. On Linux it needs Hyprland with its Lua config; on macOS the Vendetta app must be running. A key set for two actions is refused, and a name nothing offers is noted in the log.
Schedules
Section titled “Schedules”A schedule stopped running
Section titled “A schedule stopped running”A failed or uncertain run disables its schedule until you look. Check vendetta schedule history --id ID and the agent, then:
vendetta schedule enable --id ID --acknowledge-uncertainA schedule never ran
Section titled “A schedule never ran”- The scheduler is not running:
vendetta schedule status. - Cron times are UTC unless the schedule has
--timezone. - Cron minutes missed while the scheduler was down are not caught up. A one-time schedule missed that way runs once when it returns.
Machines and people
Section titled “Machines and people”Claude in a machine says your login is unavailable
Section titled “Claude in a machine says your login is unavailable”The proxy could not refresh your login. Run /login in your own Claude on the host. vendetta claude-proxy status shows the login’s expiry and each machine’s state.
Vendetta says the machine image is another commit
Section titled “Vendetta says the machine image is another commit”The published image does not match your install. Wait and run vendetta machine image refresh, or build it with vendetta machine image build --local.
A socket path is too long
Section titled “A socket path is too long”Unix socket paths hold at most 107 bytes. Keep XDG_STATE_HOME short.
A person’s name on the tailnet does not answer
Section titled “A person’s name on the tailnet does not answer”A name works only once a tailnet admin has defined its Service and approved this machine as its host, and only on a tagged machine. vendetta instance list says what each name waits for; the port address works meanwhile. See Plugins.
Machines are gone after a reboot with Podman
Section titled “Machines are gone after a reboot with Podman”Podman restarts them only with linger and podman-restart.service: loginctl enable-linger and systemctl --user enable podman-restart.service.