CloudWorkstation Troubleshooting Guide¶

# Start the daemon
cws daemon start

# Verify it's running
cws daemon status

# Check if something is using port 8947
lsof -i :8947

# Kill conflicting process if found
kill -9 <PID>

# Try starting again
cws daemon start

# Check current credentials
aws sts get-caller-identity

# Configure if needed
aws configure

# Check AWS profile
echo $AWS_PROFILE

# Set profile if needed
export AWS_PROFILE=your-profile-name

# Or specify directly
cws launch python-ml my-project --profile your-profile-name

# CloudWorkstation auto-discovers VPC/subnet (new feature!)
cws launch python-ml my-project

# If auto-discovery fails, check your VPC setup
aws ec2 describe-vpcs --query 'Vpcs[?IsDefault==`true`]'

# Create a default VPC
aws ec2 create-default-vpc

# Or specify manually (advanced)
cws ami build python-ml --vpc vpc-12345 --subnet subnet-67890

# Check current instances and costs
cws list

# Stop unused instances
cws stop instance-name

# Use hibernation to preserve work and reduce costs
cws hibernate instance-name

# Enable auto-hibernation for idle instances
cws idle enable

# Use smaller instance sizes
cws launch python-ml my-project --size S

# Use spot instances (up to 90% savings)
cws launch python-ml my-project --spot

# Check institutional pricing discounts
cws pricing show

# Check instance status
cws list

# Ensure instance is running
cws start instance-name

# Get fresh connection info
cws connect instance-name

# Check security group settings
cws list --verbose

# Wait for instance to fully boot (can take 2-3 minutes)
# Then try connecting again

# Use larger instance size
cws stop instance-name
cws launch python-ml instance-name --size L

# Or add more storage
cws storage create extra-space XL
cws storage attach extra-space instance-name

# Validate template before launching
cws templates validate python-ml

# Check template contents
cws templates info python-ml

# Apply additional packages to running instance
cws apply docker-tools instance-name

# Force refresh template cache
rm -rf ~/.cloudworkstation/templates
cws templates

# Use AMI-based templates for reliability
cws templates | grep "(AMI)"

# Try different region
cws launch python-ml my-project --region us-east-1

# Use different instance size
cws launch python-ml my-project --size M

# Check region availability
aws ec2 describe-availability-zones --region us-west-2

# For GUI issues on macOS
# Allow keychain access when prompted (now shows "CloudWorkstation")

# For TUI display issues
export TERM=xterm-256color
cws tui

# For interface problems, use CLI as backup
cws list
cws connect instance-name

# Set debug mode
export CWS_DEBUG=1

# Check daemon logs
cws daemon logs

# Or run commands with verbose output
cws launch python-ml my-project --verbose

# Verify AWS CLI version (need v2+)
aws --version

# Check CloudWorkstation version
cws version

# Verify network connectivity
curl -I https://ec2.amazonaws.com

# Stop daemon
cws daemon stop

# Clear cache and state
rm -rf ~/.cloudworkstation/

# Restart fresh
cws daemon start

# CloudWorkstation version
cws version

# Daemon status
cws daemon status

# AWS account info (no credentials)
aws sts get-caller-identity --query 'Account'

# Operating system
uname -a

# Error message (full text)

# Force stop and restart
cws stop instance-name --force
cws start instance-name

# Or delete and recreate
cws save instance-name backup-template  # Save work first
cws delete instance-name
cws launch backup-template instance-name-new

# Check if hibernated (data may be preserved)
cws list --all

# Look for recent AMI snapshots
cws ami list

# Contact AWS support for EBS snapshot recovery if critical

# Immediately stop all instances
cws list | grep running | awk '{print $1}' | xargs -I {} cws stop {}

# Check what's still running
cws list

# Review hibernation options for the future
cws idle profile list