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

# Troubleshooting

> Fix common VectorLint errors with providers, configuration, and CI.

This page covers runtime errors after VectorLint is installed. For setup, see [Installation](/installation). For config debugging, see [Project Configuration](/project-config).

## Find your error

| What you see                                                                                          | Go to                                                       |
| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `vectorlint: command not found`                                                                       | [Command not found](#command-not-found)                     |
| `LLM_PROVIDER is required and must be either 'azure-openai', 'anthropic', or 'openai'. Received: ...` | [Provider not recognized](#provider-not-recognized)         |
| `AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY must both be provided or both be omitted`                | [Bedrock credential mismatch](#bedrock-credential-mismatch) |
| `Error: rules path does not exist: <path>`                                                            | [Rules path missing](#rules-not-running-on-a-file)          |
| Run completes but prints nothing                                                                      | [No output from a run](#no-output-from-a-run)               |
| Rules you configured aren't firing                                                                    | [Rules not running on a file](#rules-not-running-on-a-file) |
| VECTORLINT.md token warning                                                                           | [VECTORLINT.md too large](#vectorlintmd-is-too-large)       |
| CI exits non-zero with no findings                                                                    | [CI fails with no findings](#ci-fails-with-no-findings)     |

## Installation

### Command not found

The npm global bin directory isn't on your `PATH`. Add it:

```bash theme={null}
npm bin -g
export PATH="$PATH:$(npm bin -g)"
```

Add the export to your shell profile (`.zshrc`, `.bashrc`) to persist it. VectorLint requires Node.js 18+.

## Provider and API keys

### Provider not recognized

The full error:

```
LLM_PROVIDER is required and must be either 'azure-openai', 'anthropic', or 'openai'. Received: undefined
```

<Note>
  This message is stale. It lists three providers, but VectorLint accepts five: `openai`, `anthropic`, `azure-openai`, `gemini`, and `amazon-bedrock`. The schema validates all five; only the error string is wrong.
</Note>

Set `LLM_PROVIDER` in `.env` or `~/.vectorlint/config.toml`:

```toml theme={null}
[env]
LLM_PROVIDER = "openai"
```

See [Environment variables](/env-variables) for the full list.

### Bedrock credential mismatch

```
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY must both be provided or both be omitted
```

AWS credentials are an all-or-nothing pair. Either set both `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, or omit both to fall back to an IAM role or `~/.aws/credentials` profile. `AWS_REGION` is always required. See [LLM providers](/llm-providers) for full Bedrock setup.

### Authentication errors

A `401` or `Invalid API key` from your provider means the key is missing or `LLM_PROVIDER` doesn't match the key you set. Confirm the variable is present:

```bash theme={null}
echo $OPENAI_API_KEY
```

Set the key in `.env` or `~/.vectorlint/config.toml` using the exact variable name for your provider: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, or `AZURE_OPENAI_API_KEY`:

```toml theme={null}
[env]
LLM_PROVIDER = "anthropic"
ANTHROPIC_API_KEY = "sk-ant-..."
```

### No search provider for technical-accuracy rules

Rules using `evaluator: technical-accuracy` need a search provider. Without one they return reduced-confidence results. Add Perplexity:

```toml theme={null}
[env]
SEARCH_PROVIDER = "perplexity"
PERPLEXITY_API_KEY = "pplx-..."
```

## Configuration

### No output from a run

Three causes, in order of likelihood:

1. **Threshold too high.** `CONFIDENCE_THRESHOLD` filters everything. Test with a lower value:

   ```bash theme={null}
   CONFIDENCE_THRESHOLD=0.5 vectorlint doc.md
   ```

   If findings appear, tune the threshold. See [Handling false positives](/handling-false-positives).

2. **Empty RunRules.** The file matches a pattern with `RunRules=` (empty), the intentional "skip this file" syntax. Check `.vectorlint.ini`.

3. **Content passes.** Run against a file you know has issues to confirm the rule works.

### Rules not running on a file

Work through the match chain:

1. The glob must match the file path. `**/*.md` matches any Markdown file; `content/docs/**/*.md` does not match `docs/api.md`.

2. `RulesPath` must point at the directory containing your pack subdirectories:

```ini theme={null}
RulesPath=.github/rules
```

3. The pack name in `RunRules` must match the directory name exactly (case-sensitive). `RunRules=Acme` looks for an `Acme/` subdirectory inside `RulesPath`.

See [Project Configuration](/project-config) for cascade semantics: multiple matching patterns accumulate, so a file can run packs from more than one section.

### VECTORLINT.md is too large

VectorLint warns at \~4,000 tokens. A file that large degrades LLM precision and raises costs because it's prepended to every evaluation call.

Target under 800 tokens. Move detailed rules into dedicated rule pack files. [Defining your style rules](/style-guide) has an extraction prompt for distilling a full style guide.

## CI

### CI fails with no findings

The run failed before evaluation. Check:

1. The API key secret isn't reaching the job:

   ```yaml theme={null}
   env:
     OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
   ```

2. Node.js is below 18:

   ```yaml theme={null}
   - uses: actions/setup-node@v4
     with:
       node-version: lts/*
   ```

3. Globs aren't expanding. Some CI shells don't expand unquoted globs. Resolve files explicitly:

   ```bash theme={null}
   find content/docs -name "*.md" | xargs vectorlint
   ```

## Getting more help

* [GitHub issues](https://github.com/TRocket-Labs/vectorlint/issues)
* [CLI reference](/cli-reference): flags and exit codes
* [Environment variables](/env-variables): variable names and precedence
* [Project Configuration](/project-config): `.vectorlint.ini` pattern matching