vx-troubleshooting（vx 故障排除）

VX Troubleshooting Guide

Quick triage: Start with vx doctor for diagnostics. Use vx --debug <command> for detailed logs. Use vx cache clean to clear corrupted state. Check exit codes (2=tool not found, 3=install failed, 4=version not found, 5=network error).

Common Issues

Installation Failures

Tool Download Failed

Symptoms: Failed to download <tool>: network error or Connection refused

Solutions:

# Enable CDN acceleration (China users)
vx config set cdn_acceleration true

# Use mirror
vx install node --mirror https://npmmirror.com/mirrors/node

# Retry with verbose output
vx install node --verbose --debug

# Check cache and retry
vx cache clean
vx install node

Checksum Mismatch

Symptoms: Checksum mismatch: expected X, got Y

Solutions:

# Clear corrupted download
vx cache clean

# Reinstall with fresh download
vx install node@22 --force

Permission Denied

Symptoms: Permission denied or Access is denied

Solutions:

# Check VX_HOME permissions
ls -la ~/.vx

# Fix permissions (Unix)
chmod -R u+rw ~/.vx

# Run with elevated permissions if needed
sudo vx install node  # Not recommended, use user installation

Version Issues

Version Not Found

Symptoms: Version X not found for <tool>

Solutions:

# List available versions
vx versions node

# Use latest stable
vx install node@latest

# Use LTS version
vx install node@lts

# Check for typos
vx versions node | grep "20"

Version Conflict

Symptoms: Multiple versions installed, wrong version active

Solutions:

# List installed versions
vx list node --installed

# Switch to specific version
vx switch node@20

# Check which version is active
vx which node

# Remove conflicting versions
vx uninstall node@18

PATH Issues

Command Not Found

Symptoms: command not found: node after installation

Solutions:

# Verify vx shim directory is in PATH
echo $PATH | grep -o ".vx/bin"

# Add vx to PATH (add to shell config)
export PATH="$HOME/.vx/bin:$PATH"

# Or use vx directly
vx node --version

# Check shim exists
ls ~/.vx/bin/node

Wrong Version in PATH

Symptoms: System version takes precedence over vx version

Solutions:

# Check which executable is being used
which node
vx which node

# Reorder PATH (vx should come first)
export PATH="$HOME/.vx/bin:$PATH"

# Or use vx explicitly
vx node --version

Runtime Issues

Tool Crashes on Startup

Symptoms: Tool exits immediately or crashes

Solutions:

# Check tool version
vx which node
vx node --version

# Reinstall the tool
vx install node --force

# Check for missing dependencies
vx doctor

# Try with debug output
vx node --verbose script.js

Dependency Missing

Symptoms: error while loading shared libraries or DLL not found

Solutions:

# Check dependencies (Linux)
ldd $(vx which node)

# Install system dependencies
# Ubuntu/Debian
sudo apt-get install build-essential libssl-dev

# macOS (via Homebrew)
brew install openssl

# Windows - usually bundled, check PATH

Configuration Issues

vx.toml Not Loading

Symptoms: Settings in vx.toml ignored

Solutions:

# Verify file location
ls vx.toml

# Check syntax
vx check

# Validate configuration
vx config validate

# Show effective configuration
vx config show

Lock File Conflicts

Symptoms: vx.lock is out of sync

Solutions:

# Regenerate lock file
vx lock --update

# Or remove and regenerate
rm vx.lock
vx lock

Diagnostic Commands

System Information

# General diagnostics
vx doctor

# System info
vx info

# Environment check
vx check --json

# Show configuration
vx config show

Debug Mode

# Enable debug logging
vx --debug node --version

# Enable trace logging
vx --trace node --version

# Verbose output
vx --verbose install node

Cache Inspection

# Show cache location
vx cache dir

# Show cache size
vx cache info

# List cached items
vx cache list

# Clean cache
vx cache clean

Error Messages Reference

Common Errors

Exit Codes

Recovery Procedures

Complete Reset

# Backup configuration
cp -r ~/.vx ~/.vx.backup

# Remove everything
rm -rf ~/.vx

# Reinstall
vx install node go uv

# Restore configuration
cp ~/.vx.backup/vx.toml ~/.vx/

Repair Installation

# Verify and repair
vx doctor --fix

# Reinstall all tools from vx.toml
vx sync --force

# Rebuild shims
vx shim rebuild

Getting Help

Collect Diagnostics

# Generate diagnostic report
vx doctor --output diagnostics.txt

# Include in bug report
cat diagnostics.txt

Useful Information to Provide

1. vx version: vx --version
2. Operating system: vx info | grep -i os
3. Command that failed
4. Error message (use --debug)
5. Contents of vx.toml (if applicable)
6. vx doctor output

Support Channels

• GitHub Issues: https://github.com/loonghao/vx/issues
• Documentation: https://github.com/loonghao/vx#readme

Quick Triage for AI Agents

When a user reports a vx issue, follow this decision tree:

1. "command not found: vx"
   → vx is not installed. Run the install script.
   → Linux/macOS: curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install.sh | bash
   → Windows: powershell -c "irm https://raw.githubusercontent.com/loonghao/vx/main/install.ps1 | iex"

2. "Failed to download" / "network error" (exit code 5)
   → Try: vx cache clean && vx install <tool> --verbose
   → If in China: vx config set cdn_acceleration true
   → Check if GITHUB_TOKEN is set for API rate limits

3. "version not found" (exit code 4)
   → Run: vx versions <tool> to list available versions
   → The user may have a typo in the version string
   → Try: vx install <tool>@latest

4. "permission denied" (exit code 6)
   → Check: ls -la ~/.vx (Unix) or icacls %USERPROFILE%\.vx (Windows)
   → Fix: chmod -R u+rw ~/.vx
   → Never use sudo with vx

5. Tool works but wrong version
   → Run: vx which <tool> to see which version is active
   → Check: vx.toml may specify a different version
   → Run: vx switch <tool>@<version>

6. vx.toml not being picked up (exit code 7)
   → Ensure file is in the project root (same dir as .git)
   → Run: vx check to validate syntax

7. CI failing with vx
   → Ensure the GitHub Action is used: loonghao/vx@main
   → Add github-token for rate limit avoidance
   → Use cache: 'true' for faster CI runs

8. General error (exit code 1)
   → Run: vx doctor for full diagnostics
   → Run: vx --debug <command> for detailed logs
   → Check: vx cache clean to clear corrupted state