# Troubleshooting and recovery Resolve PATH, extraction, optional runtime, model and frozen-input failures. CLI version: 0.2.1 · [Read online]() ## ragvi: command not found **Terminal** ``` 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 **Terminal** ``` 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 **Terminal** ``` 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. > **Need help?** > > Report the version, OS, exact command and complete error at the CLI issue tracker. Remove keys, confidential content and private paths first. - [CLI issue tracker]() - [Full troubleshooting guide]()