Every entry below is a real failure someone hit, and the fix that shipped. Find your symptom, run the command. Env-var details live in configuration.md; the full command reference in cli.md.
Cause: eve build needs more RAM than a small VPS has — the kernel OOM-kills it. The installer normally adds a swapfile to prevent this (install.md), but skips it when free disk is too low. Add one by hand:
sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile
sudo mkswap /swapfile && sudo swapon /swapfile
cd ~/iva && npm run buildCause: before 0.1.4 the wizard saw Iva's own port as "busy", moved IVA_PORT 8723 → 8724 and left ASSISTANT_HOST on the old one — the bridge talked to a port nobody listened on.
iva update # 0.1.4+ keeps the port and syncs the host
grep -E '^(IVA_PORT|ASSISTANT_HOST)' ~/iva/.env # the two ports must match
iva restartCause: a wedged turn lives in .workflow-data, and eve re-enqueues it on every start — plain iva restart brings it right back.
iva reset # stop services, quarantine workflow + Telegram busy/queue state, restartFrom Telegram, /new resets only the current chat or forum topic. /restart resets that same conversation and then restarts the agent process. Both are handled out-of-band and work while the agent is busy. Use server-side iva reset only when the entire workflow store is damaged.
After upgrading a legacy group with no recorded Eve token, send /new as a reply to Iva's latest message once. Future resets use the exact token stored by the new channel events.
Cause: the model is read once, at process start.
iva restartCause: Telegram's Bot API download cap (providers.md) — the bridge never receives the audio. Split before sending:
ffmpeg -i note.m4a -f segment -segment_time 600 -c copy part%02d.m4aCause: old versions used a destructive recovery path when upstream history changed. Re-run the current installer; it creates a backup ref, stashes tracked and untracked customizations by exact OID, and refuses an unsafe merge:
curl -fsSL https://raw.githubusercontent.com/smixs/iva/main/install.sh | bashDo not reset or clean the checkout. If the histories cannot be combined safely, the existing version and user files remain in place and the full reason is recorded under data/logs/.
Cause: the nightly Brain pass backs your vault up to a private iva-vault GitHub repo through gh; unauthenticated gh means no off-box backup.
gh auth login # the installer already put gh on the box
systemctl --user start iva-brain.service # backup now: creates the private repo and pushesiva doctor only reports a missing vault origin — the repo creation and push happen in the nightly Brain pass; the second command runs it immediately instead of waiting for 05:00.
On an install that has not been updated since the rename the unit is still called iva-memory-doctor.service — iva doctor moves it to iva-brain.service.
Cause: Ubuntu 23.10+ blocks unprivileged user namespaces (AppArmor), so Chromium dies with "No usable sandbox". The installer writes the workaround; if it's missing:
echo '{ "args": "--no-sandbox" }' > ~/.agent-browser/config.json
agent-browser open about:blank && agent-browser close --all # launch checkThe step-by-step procedure — what to copy off the old box and how to restore it on the new one — is in deploy.md ("Moving servers").
The Brain pass commits and pushes the vault nightly at 05:00, so the remote is at most a day behind.
rm -rf ~/iva/vault
gh repo clone <user>/iva-vault ~/iva/vault
iva restartiva uninstall, with --purge to also delete code and vault — push the vault first; there is no undo. Details: cli.md.