Troubleshooting

Setup Issues

"Cloud Dev Not Configured" Error

Run the init command to configure your environment:

./ds cloud-dev init
source ~/.zshrc  # Apply changes

AWS Credentials Expired

Re-authenticate with SSO:

# On your local machine
aws sso login

# Or specify profile
aws sso login --profile devstride-yourname

SSH Key Not Found

If you see "SSH key not found" when trying to connect:

./ds cloud-dev setup

This will generate new SSH keys and configure your local SSH config.

Connection Issues

SSH Connection Timeout

Cause: Instance may be stopped or overloaded.

Solution:

# Check instance status
./ds cloud-dev list

# If stopped, start it
./ds cloud-dev start

# If running but unresponsive, restart
./ds cloud-dev stop
./ds cloud-dev start

"Permission denied (publickey)"

Cause: SSH key mismatch between local and instance.

Solution:

# Re-run setup to regenerate keys
./ds cloud-dev setup

Can't Connect After IP Change

When an instance is stopped and started, it may get a new public IP.

Solution:

# Update your SSH config
./ds cloud-dev setup

# Or use SSM (doesn't need IP)
./ds cloud-dev ssm

GitHub Issues

Can't Clone Repository

Cause: GitHub SSH key not added.

Solution:

1. Get the public key from your instance:

   ./ds cloud-dev ssm
   cat ~/.ssh/id_ed25519.pub
   

2. Add to GitHub: https://github.com/settings/ssh/new
3. Test on instance:

   ssh -T git@github.com
   

GitHub CLI Can't Add Key

If gh CLI fails to add your SSH key automatically:

# Grant admin:public_key scope
gh auth refresh --hostname github.com --scopes admin:public_key

# Then retry
./ds cloud-dev setup

Database Issues

Connection Refused

Cause: Database connection string incorrect or Neon branch doesn't exist.

Solution:

1. Verify your Neon branch exists in the Neon Console
2. Check .env has correct DB_CONNECTION_STRING
3. Test connection:

   ./ds migrations run
   

Need to Reset Database

# On the instance
./ds script reset-db

Or remotely:

./ds cloud-dev reset-database

Performance Issues

Backend Crashes or Slow

Cause: Usually resource exhaustion.

Solution:

1. Check resources on the instance:

   htop
   

2. If memory is exhausted, restart the backend:

   pkill -f 'sst dev'
   ./ds run backend
   

3. If persistent, consider stopping other processes or using a larger instance type.

High CPU from esbuild

Cause: File watcher issues.

Solution: The instance is pre-configured with increased inotify limits. If you still see issues:

# Check current limits
cat /proc/sys/fs/inotify/max_user_watches

# Should be 524288 or higher

Cleanup Issues

Destroy Command Fails

If destroy fails to clean up all resources:

# Force destroy
./ds cloud-dev destroy -f

# If still failing, manually check AWS Console for:
# - EC2 instances named devstride-dev-yourname
# - VPCs named devstride-dev-yourname
# - Security groups
# - Elastic IPs

Orphaned Resources

After a failed destroy, clean up manually:

# List what's left
aws ec2 describe-instances \
  --filters "Name=tag:Name,Values=devstride-dev-*" \
  --query 'Reservations[].Instances[].InstanceId' \
  --profile devstride-yourname

Getting Help

If you're stuck:

1. Check the logs on the instance:

   ./ds cloud-dev ssm
   sudo journalctl -u cloud-init
   

2. Try connecting via SSM (bypasses SSH):

   ./ds cloud-dev ssm
   

3. Ask in the team Slack channel