Skip to main content
Vibgrate Graph: over 24% fewer tokens, same results

Troubleshooting

Troubleshooting guides and solutions

9
FAQs

FAQs

What are common errors when running the CLI on Windows?

Common issues: 'node' is not recognized (Node.js not in PATH — restart terminal or reinstall). Execution policy errors in PowerShell (run Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned). Long path errors (enable long paths: registry key HKLM\SYSTEM\CurrentControlSet\Control\FileSystem LongPathsEnabled=1). Permission denied on node_modules (run terminal as Administrator or fix folder permissions).

What are common errors when running the CLI on macOS?

Common issues: 'command not found: vibgrate' (package not installed globally or npx not used). Permission denied (use sudo cautiously or fix with sudo chown -R $(whoami) ~/.npm). EACCES errors (npm cache permissions — run npm cache clean --force). SSL certificate errors (try npm config set strict-ssl false temporarily). xcode-select errors (run xcode-select --install).

How do I fix permission denied errors on macOS?

For npm global packages: avoid sudo, instead fix ownership with sudo chown -R $(whoami) ~/.npm and sudo chown -R $(whoami) /usr/local/lib/node_modules. For project files: chmod -R u+rw your-project/. If using nvm, permission issues are rare since packages install in your home directory. For EACCES on .vibgrate folder: chmod -R 755 .vibgrate.

How do I fix permission denied errors on Windows?

Run terminal as Administrator (right-click > Run as Administrator). For persistent issues: check folder permissions (Properties > Security tab), ensure your user has Full Control. For npm global packages: consider using nvm-windows which avoids permission issues. If antivirus is blocking: add node.exe and your project folder to exclusions. For file locking errors: close VS Code or other editors accessing the files.

I'm getting Node.js version errors. What should I do?

Vibgrate requires Node.js >= 22.0.0. Check your version: node --version. If too old, upgrade using nvm (nvm install 22), Homebrew (brew upgrade node), or download from nodejs.org. If you have multiple Node versions, use nvm or similar to switch: nvm use 22. CI environments should specify node-version: 22 in their setup steps.

The scan says lockfile not found. Is that a problem?

Lockfile warnings indicate you don't have a package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb. This affects dependency graph analysis and duplicate detection but won't block the scan. For full analysis, generate a lockfile: npm install (creates package-lock.json), yarn install (creates yarn.lock), or pnpm install (creates pnpm-lock.yaml).

Why is the scan taking a long time?

Slow scans are usually due to registry network calls. Try --concurrency 16 to increase parallel registry requests. For repeated scans, results are cached. If scanning many projects in a monorepo, consider excluding irrelevant directories. For air-gapped or slow networks, use --offline with a pre-downloaded manifest.

The scan mentions missing security scanners. What should I do?

Extended security scanners check for installed tools like npm audit. If tools are missing, install the recommended tools manually (for example via Homebrew on macOS). These scanners are optional — core drift analysis runs regardless of whether security tools are installed.

I'm getting network timeout errors during scans. How do I fix this?

Network timeouts usually occur when querying package registries. Solutions: increase timeout with --timeout 60000, reduce concurrency with --concurrency 4, or use offline mode with a pre-downloaded manifest. If behind a corporate proxy, ensure npm is configured: npm config set proxy http://proxy:port. Check your network connectivity to registry.npmjs.org.