Troubleshooting and recovery

ragvi: command not found

uv tool update-shell

Restart the terminal and run ragvi --version. Confirm Python 3.12 and the intended isolated tool installation.

Start with installation checks

ragvi health
ragvi verify

PASS means a check succeeded, WARN can describe an optional unavailable runtime, and FAIL requires action. A missing semantic extra does not block BM25. Install extras with the pinned command in Installation.

Input or reference validation fails

• Use UTF-8 input and the supported document-only schemas.
• Separate question files from document exports.
• Use unique question IDs and exact original-span source IDs/quotes/hashes.
• Use writable output/cache roots when source folders are read-only.
• Use a fresh comparison after changing frozen inputs; resume cannot accept configuration changes.

Model-backed experiments fail

Check the extra/provider, model’s operation, endpoint, disk/memory and explicit --env-file. Strict rewriting/compression JSON failures are retained with private failure evidence. No automatic retry invents an output; original-text fallback must be selected and is disclosed.

Optional workspace recovery

ragvi workspace restore customer-support

An existing edited workspace is moved to a timestamped backup before bundled files are restored. This command is for named workspaces; portable data does not need workspace setup.

• CLI issue tracker

• Full troubleshooting guide