VDK Docs
Support

Troubleshooting

Documentation for troubleshooting

Common Issues & Solutions

This guide covers the most frequently encountered issues when using VDK CLI and their solutions.

Installation Issues

Node.js Version Compatibility

Problem: VDK CLI requires Node.js 22.0.0 or higher.

Error: VDK CLI requires Node.js >= 22.0.0. You are using v16.14.0

Solution:

# Check current Node.js version
node --version

# Install/update Node.js using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

# Or download from nodejs.org
# https://nodejs.org/en/download/

Permission Errors on Global Install

Problem: Permission denied when installing globally.

Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@vdk'

Solution:

# Option 1: Configure npm to use different directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Option 2: Use sudo (less secure)
sudo npm install -g @vibe-dev-kit/cli --unsafe-perm

# Option 3: Use pnpm (recommended)
pnpm add -g @vibe-dev-kit/cli

Module Not Found Errors

Problem: VDK CLI installed but not found in PATH.

vdk: command not found

Solution:

# Check if VDK is installed
npm list -g @vibe-dev-kit/cli

# If installed, check PATH
echo $PATH
which vdk

# Add npm global bin to PATH
npm config get prefix
export PATH=$(npm config get prefix)/bin:$PATH

# Make permanent
echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc

Project Initialization Issues

Project Path Not Found

Problem: Specified project path doesn't exist.

❌ Project path does not exist: /path/to/nonexistent/project

Solution:

# Check if path exists
ls -la /path/to/project

# Use absolute path
vdk init --projectPath "$(pwd)"

# Or navigate to project first
cd /path/to/project
vdk init

Permission Denied on Project Files

Problem: Cannot read project files due to permissions.

Error: EACCES: permission denied, scandir '/project/.git'

Solution:

# Check file permissions
ls -la /project

# Fix permissions if needed
chmod -R u+r /project

# Or add problematic directories to ignore patterns
vdk init --ignorePattern "**/.git/**" "**/node_modules/**"

Large Project Timeout

Problem: Scanner times out on large projects.

Error: Scan timeout after 120000ms

Solution:

# Increase timeout
export VDK_SCAN_TIMEOUT=300000

# Use more aggressive ignore patterns
vdk init --ignorePattern "**/node_modules/**" "**/dist/**" "**/build/**" "**/.next/**"

# Disable deep scanning for initial scan
vdk init --no-deep

# Scan specific directories only
vdk init --projectPath ./src

Scanning & Analysis Issues

Memory Issues with Large Codebases

Problem: JavaScript heap out of memory during scanning.

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Solution:

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=8192"

# Use streaming processing
vdk init --stream-processing

# Reduce scan scope
vdk init --projectPath ./src --ignorePattern "**/tests/**" "**/*.test.*"

# Disable memory-intensive analyzers
export VDK_DISABLE_ANALYZERS=typescript-ast,dependency-graph

Analyzer Failures

Problem: Specific language analyzers fail.

Error: TypeScript analyzer failed: Cannot parse tsconfig.json

Solution:

# Check configuration files
cat tsconfig.json | jq .  # Validate JSON

# Disable problematic analyzers
export VDK_DISABLE_ANALYZERS=typescript
vdk init

# Use verbose mode to debug
VDK_DEBUG=true vdk init --verbose

# Update analyzer configurations
vdk config set analyzers.typescript.strictMode false

Pattern Detection Issues

Problem: VDK fails to detect known patterns or frameworks.

⚠️ No frameworks detected. Using generic rules.

Solution:

# Ensure package.json exists and is valid
cat package.json

# Check if files are in expected locations
ls -la src/
ls -la components/

# Use deep scanning
vdk init --deep

# Manually specify framework
vdk config set project.framework nextjs

# Check ignore patterns aren't too aggressive
vdk init --ignorePattern "**/node_modules/**" --use-gitignore false

IDE Integration Issues

Claude Code Not Detected

Problem: VDK cannot detect Claude Code installation.

❌ Claude Code is not available
   - Install: npm install -g @anthropic-ai/claude-code

Solution:

# Install Claude Code
npm install -g @anthropic/claude-code

# Verify installation
claude --version

# Check PATH
which claude

# Force detection refresh
vdk integrations --scan

# Manual setup if detection fails
vdk integrations --setup claude-code

Integration Setup Failures

Problem: IDE integration setup fails.

❌ Failed to configure Claude Code integration

Solution:

# Check file permissions
ls -la .claude/

# Ensure directory is writable
chmod -R u+w .claude/

# Check disk space
df -h .

# Try manual setup
mkdir -p .claude/commands
vdk claude-code --setup

# Debug mode
VDK_DEBUG=true vdk claude-code --setup

Memory File Not Updating

Problem: CLAUDE.md not updating with latest project context.

⚠️ Claude Code memory not updated

Solution:

# Force memory update
vdk claude-code --update-memory

# Check file permissions
ls -la CLAUDE.md

# Regenerate configuration
vdk claude-code --setup

# Verify integration status
vdk claude-code --check

# Manual memory update
vdk init --overwrite
vdk claude-code --update-memory

Hub Integration Issues

Authentication Failures

Problem: Cannot authenticate with VDK Hub.

❌ Authentication failed: Invalid token

Solution:

# Check token configuration
echo $VDK_HUB_TOKEN

# Re-authenticate
vdk login

# Use explicit token
export VDK_HUB_TOKEN=your_actual_token

# Verify token validity
vdk whoami

# Check hub connectivity
vdk hub ping

Deployment Failures

Problem: Rule deployment to hub fails.

❌ Deployment failed: Network timeout

Solution:

# Check internet connectivity
ping vdk.tools

# Verify VDK Hub status
vdk hub status

# Check file sizes (hub has limits)
du -sh .ai/rules/

# Use dry run to test
vdk deploy --dry-run

# Deploy specific rules only
vdk deploy --rules react-patterns,typescript-base

Update Failures

Problem: Cannot update rules from hub.

❌ Update failed: Connection refused

Solution:

# Check hub configuration
vdk config list

# Test connectivity
curl -I https://vdk.tools/health

# Use alternative hub endpoint
export VDK_HUB_URL=https://backup.vdk.tools

# Manual rule download
vdk hub download --rule react-patterns

# Clear cache and retry
vdk cache clear
vdk update

Configuration Issues

Invalid Configuration Files

Problem: VDK configuration file is corrupted or invalid.

❌ Invalid configuration: Unexpected token in JSON

Solution:

# Validate configuration file
cat vdk.config.json | jq .

# Backup and recreate
cp vdk.config.json vdk.config.json.bak
vdk init --overwrite

# Reset to defaults
rm vdk.config.json
vdk config reset

# Manual configuration repair
vdk config set project.name my-project
vdk config set project.type web-application

Rule Validation Errors

Problem: Generated rules fail validation.

❌ Rule validation failed: Missing required frontmatter

Solution:

# Validate specific rule
vdk validate --file .ai/rules/react-patterns.md

# Fix common issues
vdk rules fix-frontmatter

# Regenerate problematic rules
vdk init --rules react-patterns --overwrite

# Use alternative template
vdk init --template minimal

# Manual rule repair
vdk rules validate --fix

Performance Issues

Slow Scanning Performance

Problem: VDK scanning is very slow.

🔍 Scanning... (this is taking longer than expected)

Solution:

# Profile scanning performance
VDK_PROFILE=true vdk init

# Use more aggressive ignore patterns
vdk init --ignorePattern "**/node_modules/**" "**/dist/**" "**/*.log" "**/.git/**"

# Disable expensive analyzers
export VDK_DISABLE_ANALYZERS=dependency-graph,ast-parsing

# Limit scan depth
vdk config set scanner.maxDepth 3

# Use incremental scanning
vdk init --incremental

High Memory Usage

Problem: VDK uses excessive memory.

Warning: High memory usage detected (2.1GB)

Solution:

# Monitor memory usage
VDK_MEMORY_PROFILE=true vdk init

# Reduce memory footprint
export VDK_MEMORY_LIMIT=1024
export NODE_OPTIONS="--max-old-space-size=2048"

# Use streaming mode
vdk init --stream

# Process in batches
vdk init --batch-size 100

# Clear caches
vdk cache clear

Debug Mode & Logging

Enable Debug Mode

Get detailed logging for troubleshooting:

# Enable global debug mode
export VDK_DEBUG=true

# Enable specific component debugging
export VDK_DEBUG_SCANNER=true
export VDK_DEBUG_INTEGRATIONS=true
export VDK_DEBUG_HUB=true

# Set log level
export VDK_LOG_LEVEL=debug

# Save debug output to file
VDK_DEBUG=true vdk init 2>&1 | tee debug.log

Log Locations

Find log files for debugging:

# VDK logs directory
ls -la ~/.vdk/logs/

# Current session logs
tail -f ~/.vdk/logs/vdk.log

# Integration-specific logs
ls -la ~/.claude/logs/
ls -la .cursor/logs/

# System logs (macOS)
log show --predicate 'process == "vdk"' --last 1h

Getting Help

Community Support

Diagnostic Information

Gather diagnostic information for support:

# System information
vdk doctor

# Configuration dump
vdk config dump

# Integration status
vdk integrations --scan
vdk claude-code --check

# Hub connectivity
vdk hub status

# Version information
vdk --version
node --version
npm --version

Report Template

When reporting issues, include:

**VDK Version**: [vdk --version output]
**Node.js Version**: [node --version output]
**Operating System**: [macOS/Linux/Windows + version]
**Project Type**: [React/Next.js/Vue/etc.]

**Steps to Reproduce**:
1. Command run: `vdk init`
2. Error occurred: [copy error message]

**Expected Behavior**:
[What should have happened]

**Actual Behavior**:
[What actually happened]

**Debug Output**:

[Paste output from VDK_DEBUG=true vdk command]


**Additional Context**:
[Any other relevant information]

Prevention & Best Practices

Regular Maintenance

# Update VDK CLI regularly
npm update -g @vibe-dev-kit/cli

# Clear caches periodically
vdk cache clear

# Validate configuration
vdk validate

# Check for updates
vdk status

Project Setup Best Practices

  1. Use gitignore: Always enable --use-gitignore
  2. Appropriate ignore patterns: Don't scan unnecessary files
  3. Regular updates: Keep rules updated as project evolves
  4. Team synchronization: Use hub for team collaboration
  5. Configuration backup: Keep vdk.config.json in version control

Performance Optimization

  1. Selective scanning: Use targeted project paths
  2. Memory management: Set appropriate Node.js memory limits
  3. Cache management: Clear caches when issues occur
  4. Incremental updates: Use --incremental for large projects
  5. Profile performance: Use profiling tools to identify bottlenecks

If you encounter an issue not covered here, please check the FAQ or report it on GitHub.

Edit on GitHub

Watch Mode

Continuous monitoring and real-time updates for VDK rules and IDE integrations

FAQ

Documentation for faq

On this page

Common Issues & Solutions
Installation Issues
Node.js Version Compatibility
Permission Errors on Global Install
Module Not Found Errors
Project Initialization Issues
Project Path Not Found
Permission Denied on Project Files
Large Project Timeout
Scanning & Analysis Issues
Memory Issues with Large Codebases
Analyzer Failures
Pattern Detection Issues
IDE Integration Issues
Claude Code Not Detected
Integration Setup Failures
Memory File Not Updating
Hub Integration Issues
Authentication Failures
Deployment Failures
Update Failures
Configuration Issues
Invalid Configuration Files
Rule Validation Errors
Performance Issues
Slow Scanning Performance
High Memory Usage
Debug Mode & Logging
Enable Debug Mode
Log Locations
Getting Help
Community Support
Diagnostic Information
Report Template
Prevention & Best Practices
Regular Maintenance
Project Setup Best Practices
Performance Optimization