> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryvoss.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common Voss setup, command, permission, and docs issues.

## `voss` is not found

Install the CLI package:

```bash theme={"theme":"github-dark"}
npm i -g @vosslang/cli
```

Then verify:

```bash theme={"theme":"github-dark"}
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:

```bash theme={"theme":"github-dark"}
voss doctor
```

Then inspect config:

```bash theme={"theme":"github-dark"}
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:

```bash theme={"theme":"github-dark"}
voss check path/to/file.voss
```

Then run:

```bash theme={"theme":"github-dark"}
voss run path/to/file.voss
```

## Docs commands fail

Install the Mintlify CLI globally:

```bash theme={"theme":"github-dark"}
npm i -g mint
```

Run docs commands from the site package:

```bash theme={"theme":"github-dark"}
cd site
npm run docs:dev
npm run docs:validate
```