troubleshooting.md

Troubleshooting

This guide covers common issues and their solutions.

Table of Contents

• Installation Issues
• Template Issues
• Runtime Issues
• Configuration Issues
• Debugging Tools

Installation Issues

Lima Not Found

Symptom:

Error: lima not found. Please install Lima first.

Solution:

macOS:

brew install lima

Linux:

# See https://lima-vm.io/docs/installation/

Verify:

limactl --version

Permission Denied on Binary

Symptom:

bash: ./claude-vm: Permission denied

Solution:

chmod +x ~/.local/bin/claude-vm

Binary Not in PATH

Symptom:

command not found: claude-vm

Solution:

Add ~/.local/bin to PATH:

# For bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify:

which claude-vm

Template Issues

Template Creation Fails

Symptom:

Error: Failed to create template

Debug:

1. Check Lima status:

   limactl list

2. Try with verbose output:

   claude-vm --verbose setup --git

3. Check Lima logs:

   tail -f ~/.lima/*/ha.stdout.log

4. Clean and retry:

   claude-vm clean
   claude-vm setup --git

Template Disk Full

Symptom:

Error: No space left on device

Solution:

1. Increase disk size:

   claude-vm clean
   claude-vm setup --disk 50 --git

2. Clean unused templates:

   claude-vm list --unused
   claude-vm clean-all

3. Check disk usage:

   claude-vm list --disk-usage

Tool Installation Fails

Symptom:

Error: Failed to install docker

Debug:

1. Check for package conflicts:

   claude-vm shell
   $ apt-cache policy docker

2. Try with verbose output:

   claude-vm --verbose setup --docker

3. Try minimal setup first:

   claude-vm clean
   claude-vm setup --git  # Minimal
   # If works, add tools incrementally

Runtime Issues

VM Won't Start

Symptom:

Error: Failed to start VM

Debug:

1. Try with verbose output:

   claude-vm --verbose shell

2. Check Lima VMs:

   limactl list

3. Check if template exists:

   claude-vm info

4. Stop any running VMs:

   limactl stop --all

Runtime Script Fails

Symptom:

Error: Runtime script failed: .claude-vm.runtime.sh
Exit code: 1

Debug:

1. Check script locally:

   bash -x .claude-vm.runtime.sh

2. Check script in VM:

   claude-vm shell
   $ cat .claude-vm.runtime.sh
   $ bash -x .claude-vm.runtime.sh

3. Comment out failing parts:

   # .claude-vm.runtime.sh
   # docker-compose up -d  # Temporarily disable
   echo "Skipping docker for now"

Command Not Found in VM

Symptom:

$ claude-vm shell docker ps
Error: docker: command not found

Solution:

1. Check if tool is installed:

   claude-vm info  # Check enabled capabilities

2. Reinstall template with tool:

   claude-vm clean
   claude-vm setup --docker --git

3. Check if tool is in PATH:

   claude-vm shell which docker

Port Already in Use

Symptom:

Error: bind: address already in use

Solution:

1. Check what's using the port:

   # On host
   lsof -i :3000

2. Use different port:

   # In your app
   PORT=3001 npm start

3. Stop conflicting service:

   # Find and stop the process
   kill <PID>

Mount Not Appearing

Symptom:

$ claude-vm shell ls /data
ls: /data: No such file or directory

Debug:

1. Check mount configuration:

   claude-vm config show

2. Verify host directory exists:

   ls -la ~/datasets

3. Check for typos in config:

   [[mounts]]
   location = "~/datasets"  # Check spelling
   mount_point = "/data"

4. Try CLI mount:

   claude-vm --mount ~/datasets:/data shell ls /data

Configuration Issues

Config Validation Fails

Symptom:

Error: Invalid configuration

Debug:

1. Run validation:

   claude-vm config validate

2. Check TOML syntax:

   # Common errors:
   [vm]
   disk = 30      # ✓ Number
   disk = "30"    # ✗ String
   
   [tools]
   docker = true  # ✓ Boolean
   docker = "yes" # ✗ String

3. Check value ranges:

   [vm]
   disk = 2000    # ✗ Out of range (max 1000)
   memory = 128   # ✗ Out of range (max 64)

Config Not Taking Effect

Symptom: Config changes don't apply.

Debug:

1. Check effective config:

   claude-vm config show

2. Check precedence:

   • CLI flags override everything
   • Then environment variables
   • Then project config
   • Then global config

3. Recreate template after config changes:

   claude-vm clean
   claude-vm setup --git

Environment Variables Not Set

Symptom:

$ claude-vm shell echo $API_KEY
# Empty

Solution:

1. Pass via CLI:

   claude-vm --env API_KEY=secret shell echo $API_KEY

2. Use env file:

   claude-vm --env-file .env shell

3. Set in runtime script:

   # .claude-vm.runtime.sh
   export API_KEY="secret"

Debugging Tools

Verbose Mode

See detailed output:

claude-vm --verbose setup --git
claude-vm --verbose shell
claude-vm --verbose "help me"

Shows:

• Lima VM logs
• Script execution
• Mount operations
• Detailed errors

Check VM Status

# List all VMs
limactl list

# Show VM details
limactl show <vm-name>

# Check VM logs
tail -f ~/.lima/<vm-name>/ha.stdout.log

Access VM Directly

# Get template name
claude-vm info

# Start template VM
limactl start <template-name>

# Shell into VM
limactl shell <template-name>

# Stop VM
limactl stop <template-name>

Check Configuration

# Validate config
claude-vm config validate

# Show effective config
claude-vm config show

# Show project info
claude-vm info

Test Scripts

# Test runtime script locally
bash -x .claude-vm.runtime.sh

# Test in VM
claude-vm shell bash -x .claude-vm.runtime.sh

Check Lima Health

# Lima version
limactl --version

# Lima status
limactl list

# Lima logs
tail -f ~/.lima/*/ha.stdout.log

Common Error Messages

"lima not found"

Install Lima:

brew install lima  # macOS

"Permission denied"

Make binary executable:

chmod +x ~/.local/bin/claude-vm

"Runtime script failed"

Debug script:

bash -x .claude-vm.runtime.sh
claude-vm --verbose shell

"Package not found"

Check package name:

apt-cache search <package>

Add repository if needed:

[packages]
setup_script = """
# Add repository
"""

"No space left on device"

Increase disk or clean templates:

claude-vm clean-all
claude-vm setup --disk 50 --git

Getting More Help

Check Logs

Lima logs:

tail -f ~/.lima/*/ha.stdout.log

VM logs:

claude-vm shell journalctl -f

Report Issues

1. Run with --verbose:

   claude-vm --verbose setup --git > debug.log 2>&1

2. Include in bug report:

   • claude-vm --version
   • limactl --version
   • Operating system
   • Debug log
   • Configuration file

3. Open issue on GitHub: https://github.com/themouette/claude-vm/issues

Next Steps

• Usage Guide - Learn all commands
• Configuration - Configure Claude VM
• Templates - Understand templates
• Development - Build from source