Skip to content

troubleshooting.md

Latest commit

 

History

History
278 lines (177 loc) · 3.79 KB

troubleshooting.md

File metadata and controls

278 lines (177 loc) · 3.79 KB

Troubleshooting

Common issues and solutions.

Installation Issues

"command not found: vx"

The vx binary is not in your PATH.

Solution:

  1. Check installation location

  2. Add to PATH:

    export PATH="$HOME/.local/bin:$PATH"

  3. Restart your terminal

Permission denied during installation

Solution:

# Don't use sudo with the install script
# Instead, ensure ~/.local/bin exists and is writable
mkdir -p ~/.local/bin
chmod 755 ~/.local/bin

Tool Installation Issues

"Failed to download"

Network or URL issues.

Solutions:

  1. Check internet connection

  2. Try again (transient error)

  3. Check proxy settings:

    export HTTP_PROXY=http://proxy:port
export HTTPS_PROXY=http://proxy:port

"Version not found"

The specified version doesn't exist.

Solutions:

  1. Check available versions:

    vx versions <tool>

  2. Use a valid version specifier

  3. Clear version cache:

    vx clean --cache

"Checksum mismatch"

Downloaded file is corrupted.

Solutions:

  1. Clear cache and retry:

    vx clean --cache
vx install <tool>

  2. Check disk space

Execution Issues

"Tool not found" after installation

The tool was installed but can't be found.

Solutions:

  1. Check installation:

    vx which <tool>

  2. Verify store directory:

    ls ~/.local/share/vx/store/<tool>/

  3. Try reinstalling:

    vx install <tool> --force

Wrong version being used

Solutions:

  1. Check version resolution:

    vx --verbose <tool> --version

  2. Check vx.toml in current directory

  3. Check global config:

    vx config show

"Permission denied" when running tool

Solutions:

  1. Check file permissions:

    ls -la ~/.local/share/vx/store/<tool>/<version>/

  2. Fix permissions:

    chmod +x ~/.local/share/vx/store/<tool>/<version>/<binary>

Configuration Issues

"vx.toml not found"

Solutions:

  1. Check current directory

  2. Create configuration:

    vx init

"Invalid configuration"

TOML syntax error.

Solutions:

  1. Validate TOML syntax
  2. Check for common issues:
    • Missing quotes around strings
    • Incorrect indentation
    • Invalid characters

Environment variables not set

Solutions:

  1. Check [env] section in vx.toml

  2. Verify with:

    vx dev -c "env | grep MY_VAR"

Shell Integration Issues

Completions not working

Solutions:

  1. Regenerate completions:

    vx shell completions bash > ~/.local/share/bash-completion/completions/vx

  2. Restart shell

  3. For Zsh, ensure compinit is called

Auto-switching not working

Solutions:

  1. Verify shell integration is set up:

    echo $VX_ENV

  2. Re-add to shell profile:

    eval "$(vx shell init bash)"

Performance Issues

Slow startup

Solutions:

  1. Use lazy loading in shell profile

  2. Cache init script:

    vx shell init bash > ~/.vx-init.sh
source ~/.vx-init.sh

High disk usage

Solutions:

  1. Check usage:

    vx cache info

  2. Clean up:

    vx clean --all

  3. Remove unused versions:

    vx uninstall <tool> <version>

Getting Help

Debug Output

Enable debug output for detailed information:

vx --debug <command>

Verbose Output

vx --verbose <command>

Check Version

vx --version

Report Issues

If you can't resolve an issue:

  1. Search existing issues
  2. Create a new issue with:
    • vx version
    • OS and shell
    • Steps to reproduce
    • Error messages
    • Debug output