Troubleshooting - Voss Docs

`voss` is not found

Install the CLI package:

npm i -g @vosslang/cli

Then verify:

voss --help

If you manage Python yourself, pip install voss is the direct Python package path. For Voss development, use pip install -e ".[dev]" from a source checkout.

Provider or model setup fails

Run diagnostics:

voss doctor

Then inspect config:

voss config --show

The agent will not edit a file

Check the current mode and scope.

plan mode denies mutating tools.
edit mode only allows scoped file writes.
shell_run is denied in edit mode.

Use voss edit <path> for bounded edits, or explicitly approve scope expansion when Voss asks.

A `.voss` file does not run

Check it first:

voss check path/to/file.voss

Then run:

voss run path/to/file.voss

Docs commands fail

Install the Mintlify CLI globally:

npm i -g mint

Run docs commands from the site package:

cd site
npm run docs:dev
npm run docs:validate

​voss is not found

​Provider or model setup fails

​The agent will not edit a file

​A .voss file does not run

​Docs commands fail

`voss` is not found

Provider or model setup fails

The agent will not edit a file

A `.voss` file does not run

Docs commands fail