Skip to main content
This page covers runtime errors after VectorLint is installed. For setup, see Installation. For config debugging, see Project Configuration.

​
Find your error

​
Installation

​
Command not found

The npm global bin directory isn’t on your PATH. Add it:
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:
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.
Set LLM_PROVIDER in .env or ~/.vectorlint/config.toml:
See Environment variables for the full list.

​
Bedrock credential mismatch

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 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:
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:

​
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:

​
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:
    If findings appear, tune the threshold. See 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:
  1. 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 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 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:
  2. Node.js is below 18:
  3. Globs aren’t expanding. Some CI shells don’t expand unquoted globs. Resolve files explicitly:

​
Getting more help