Troubleshooting

Start with Verify connection in the app — it launches the server the exact way your agent will and names the failure. This page covers each named cause, plus updates, requirements, and where to get help.

System requirements

• macOS 13 (Ventura) or later — one universal app for Apple silicon and Intel.
• Node 20 or newer, on your shell's PATH — used by your agent to launch Veri's MCP server. The Veri app itself needs no Node; a machine without it can browse and edit knowledge bases fine, but agents can't connect until it's installed.

Verify connection failures

"No node executable in your shell"

Your login shell has no node on PATH. Install Node 20+ — brew install node, or the installer from nodejs.org; either works. Then verify again.

Veri probes your login shell — the same environment a terminal-launched agent resolves node in — so Homebrew, nvm, and fnm installs are all found. If you use a version manager and still see this, make sure it activates in login shells and has a default version set (for nvm: nvm alias default 20).

"Node is too old"

A node was found, but below version 20 — the server won't start under it. Upgrade (brew upgrade node, or your version manager's equivalent) and verify again.

"Server file missing"

The path in .mcp.json doesn't exist on disk. Usual causes: the config was written on another machine (a teammate committed it), the app was moved or removed, or — in a source checkout — the MCP package isn't built (npm run build -w packages/mcp). With the installed app, re-run Set up connection to rewrite the path for this machine.

"Wrong project root"

The server launches and answers, but it's serving a different directory than the project open in Veri — typically a config carried over from a moved or renamed folder. Click Fix path; it rewrites only the root argument and leaves the rest of the entry alone.

"The server didn't answer"

Everything looked right, but no MCP handshake came back. The panel shows the server's error output — read it, and if it doesn't point anywhere, copy it into a GitHub issue along with your app and macOS versions.

Agent doesn't see the tools

Verification is green but Claude Code doesn't list the veri server (check with /mcp):

• Restart the session. Agent apps read .mcp.json on launch; a session started before setup won't have it.
• Check where the agent was started. Project-scoped config only applies to sessions launched in that project directory (or below it).
• First use may need approval. Claude Code asks before using a project's .mcp.json servers; if it was declined once, run claude mcp reset-project-choices and restart.

The log file

Veri writes a plain-text log to ~/Library/Logs/Veri/main.log — in Finder: Go ▸ Go to Folder… ▸ ~/Library/Logs/Veri. It records app lifecycle (launch, project opens, quit), update-check outcomes including failures, and agent-connection config writes. It never contains your documents or any knowledge-base content — paths and outcomes only.

The file is capped at 512 KB; past that it rolls to main.old.log and starts fresh, so the two together never exceed about 1 MB. The log stays on your machine: Veri ships no telemetry, and the only way it reaches anyone is you attaching it to an issue.

Updates and rollback

• How updates work: the app checks GitHub Releases, downloads in the background, and applies only when you say "restart now" or at next quit. A running session is never interrupted.
• Offline is fine: no network, or an unreachable feed, just means no update this time — the app stays fully usable and shows no error. The failed check is recorded in the log file, which is the only place it is visible at all.
• Roll back: quit Veri, download the older version's DMG from the releases page (every release keeps its artifacts), and drag it into Applications over the current one. Your knowledge bases are unaffected — they're plain files in your repos, and the on-disk format carries a version marker so an older app states a mismatch rather than misreading newer files.

Gatekeeper warnings

Releases are signed and notarized; macOS should open Veri without ceremony. If you see a "can't be opened" or unidentified-developer warning, don't override it — you may have an artifact that didn't come from GitHub Releases. Re-download from there and report it.

Getting help

GitHub Issues is the support channel, and the fastest path there is Help ▸ Report an Issue… inside the app — it opens a new issue with your Veri and macOS versions already filled in. Add what you expected, what happened, and attach ~/Library/Logs/Veri/main.log; for connection problems, include the exact text Verify connection showed. Veri ships no telemetry: nothing is reported automatically, so an issue from you is the only way a problem in the field gets known.