Troubleshooting

Common issues, error messages, and solutions for VGuard CLI and Cloud.

Diagnostic Command

Always start by running the built-in health check:

npx vguard doctor

This validates your config, hooks, agent adapters, and Cloud connection. Fix any issues it reports before investigating further.

Debug Logging

Enable verbose output to see exactly what VGuard is doing:

VGUARD_DEBUG=1 npx vguard lint

This prints each rule evaluation, file matching, and config resolution step.

Common Issues

Hooks Not Firing

Symptoms: VGuard rules are not enforcing during AI coding sessions.

Checklist:

Verify hooks exist: check .vguard/hooks/ for hook scripts
Verify agent config: for Claude Code, check .claude/settings.json for VGuard entries
Regenerate: npx vguard generate
Check permissions: hook scripts must be executable (chmod +x on macOS/Linux)

Config Not Found

Symptoms: vguard doctor reports "No config file found".

Checklist:

Ensure one of these files exists in your project root:
- vguard.config.ts (recommended)
- vguard.config.js
- .vguardrc.json
- "vguard" field in package.json
If using TypeScript config, ensure tsx or ts-node is available
Re-run npx vguard init to regenerate

Cloud Connection Fails

Symptoms: vguard doctor shows a red mark next to "Cloud connection".

Checklist:

Verify you are logged in: npx vguard cloud login
Check that cloud.enabled is true in your config
Verify the cloud.projectId matches a project in your dashboard
Check your API token is valid in Settings > API Tokens
Re-connect: npx vguard cloud connect

Rules Not Matching Expected Files

Symptoms: A rule you enabled does not report violations on files you expect.

Checklist:

Check if the rule is disabled in config: rules: { 'rule-id': false }
Check file patterns: some rules only match specific extensions (e.g. .ts, .tsx)
Check severity: info rules do not block and may be easy to miss
Run a targeted lint: npx vguard lint --rule security/branch-protection

Preset Conflicts

Symptoms: Unexpected rule behavior after adding multiple presets.

Presets are applied in declaration order — the last preset wins when two presets configure the same rule differently. Reorder your presets in vguard.config.ts to prioritize the one you want. User-level rules config always takes highest priority.

Error Codes

Code	Meaning
`MISSING_API_KEY`	No `X-API-Key` header sent. Re-run `cloud connect`
`INVALID_API_KEY`	Token not recognized. Create a new token in dashboard
`RATE_LIMITED`	Exceeded 100 requests/minute. Wait and retry
`SUBSCRIPTION_INACTIVE`	Plan canceled. Renew in billing settings
`REPO_LIMIT_EXCEEDED`	Too many projects for your plan. Upgrade or remove projects
`EMPTY_BODY`	Ingest request had no records. Check hook scripts
`NO_VALID_RECORDS`	Records were malformed or outside retention window

FAQ

Does VGuard work without Cloud?

Yes. VGuard is fully functional as a local CLI tool. Cloud adds analytics, alerts, and team visibility but is entirely optional.

What data does Cloud collect?

Cloud receives rule hit metadata only: rule ID, severity, file path, tool name, and timestamp. It does not receive file contents, code diffs, or AI conversation transcripts.

Can I use VGuard with multiple AI agents?

Yes. Configure multiple agents in your config:

agents: ['claude-code', 'cursor', 'codex']

Claude Code gets runtime enforcement. Cursor, Codex, and OpenCode receive advisory guidance files.

How do I update VGuard?

npx vguard upgrade --check   # Check for updates
npx vguard upgrade            # Apply updates

After upgrading, regenerate hooks: npx vguard generate

How do I completely remove VGuard?

npx vguard eject   # Export standalone hooks (optional)
npm uninstall @solanticai/vguard

Then remove the .vguard/ directory and VGuard entries from .claude/settings.json.