Skip to content

Troubleshooting Guide

Jump to bottom
Erik Meinders edited this page Sep 9, 2025 · 1 revision

Troubleshooting Guide

Comprehensive troubleshooting guide for common cloudX-proxy issues.

Quick Diagnosis

First Steps

When experiencing issues, start with these diagnostic commands:

# Check versions and basic setup
python --version
uvx --version
aws --version

# Verify AWS authentication
aws sts get-caller-identity --profile your-profile

# Test Session Manager plugin
aws ssm start-session --target i-1234567890abcdef0 --profile your-profile

# List configured hosts
uvx cloudx-proxy list --detailed

# Test direct connection
uvx cloudx-proxy connect i-1234567890abcdef0 22 --profile your-profile

Installation & Setup Issues

Python/Installation Problems

"python not found" or version issues

# Check Python installation and version
python --version
python3 --version
which python
which python3

Solutions:

  • Windows: Install Python from python.org and check "Add to PATH"
  • macOS: Use Homebrew: brew install python@3.11
  • Linux: Install via package manager: apt install python3 or yum install python3
  • Version too old: Update to Python 3.9+ before proceeding

"uvx command not found"

# Install or update uv
pip install uv
# or update existing installation
pip install --upgrade uv

# Verify installation
uvx --version

Solutions:

  • Restart terminal after installation
  • Check if ~/.local/bin is in PATH (Linux/macOS)
  • Use python -m pip install uv if regular pip fails

Package installation errors

# Clear uv cache and retry
uv cache clean
uvx cloudx-proxy setup

# Check for permission issues
ls -la ~/.cache/uv/

AWS CLI Issues

"aws command not found"

Check installation:

which aws
aws --version

Solutions:

  • Install AWS CLI v2 (not v1): Installation Guide
  • Windows: Add installation directory to PATH
  • macOS/Linux: Ensure /usr/local/bin is in PATH
  • Restart terminal after installation

Credential problems

# Check credentials configuration
aws configure list --profile your-profile
aws configure list-profiles

# Test credentials
aws sts get-caller-identity --profile your-profile

Common Issues:

  • "Unable to locate credentials": Run aws configure --profile your-profile
  • "Access Denied": Check IAM permissions and user ARN format
  • "Invalid security token": For temporary credentials, re-authenticate
  • "Region not specified": Set default region in profile

AWS CLI v1 vs v2 conflicts

# Check which version is installed
aws --version

# If v1 is installed, remove it first
pip uninstall awscli
# Then install v2 using the official installer

Session Manager Plugin Issues

"Session Manager plugin not found"

# Test plugin installation
session-manager-plugin

Solutions:

  • Install plugin: Session Manager Plugin Guide
  • macOS: May need to add to PATH manually
  • Windows: Restart terminal after installation
  • Linux: Check if /usr/local/sessionmanagerplugin/bin is in PATH

Plugin permission issues (macOS)

  • Allow plugin in System Preferences → Security & Privacy
  • Run: sudo spctl --master-disable (temporarily, re-enable after)

Connection Issues

VSCode Connection Problems

"Could not establish connection"

# Check VSCode SSH configuration
cat ~/.ssh/vscode/config

# Verify config file path in VSCode settings
# "remote.SSH.configFile": "~/.ssh/vscode/config"

Solutions:

  • Verify remote.SSH.configFile points to correct location
  • Check SSH config file permissions: chmod 600 ~/.ssh/vscode/config
  • Ensure SSH directory permissions: chmod 700 ~/.ssh/vscode

"Host not found" in VSCode

# List configured hosts
uvx cloudx-proxy list --detailed

# Check SSH config syntax
ssh -F ~/.ssh/vscode/config -T cloudx-dev-myserver

Solutions:

  • Run setup again if hosts are missing
  • Check for typos in hostname
  • Verify SSH config includes the host entry

Connection timeout during setup

Check timeouts in VSCode settings:

{
    "remote.SSH.connectTimeout": 90,
    "remote.SSH.serverInstallTimeout": 180,
    "remote.SSH.showLoginTerminal": true
}

Common causes:

  • Instance startup taking longer than expected (increase timeout to 120-180s)
  • Network latency (increase both timeouts by 50%)
  • First-time VSCode server installation (increase serverInstallTimeout to 300s)

"Installing server" hangs or fails

# Check instance logs for VSCode server issues
ssh cloudx-dev-myserver "journalctl -f"

Solutions:

  • Increase serverInstallTimeout to 300+ seconds
  • Check instance internet connectivity
  • Verify instance has sufficient disk space
  • Try connecting via terminal first: ssh cloudx-dev-myserver

AWS Connection Problems

Instance startup issues

# Check instance state
aws ec2 describe-instances --instance-ids i-1234567890abcdef0 --profile your-profile

# Check SSM agent status
aws ssm describe-instance-information --filters "Key=InstanceIds,Values=i-1234567890abcdef0" --profile your-profile

Common issues:

  • Instance stuck in "pending": Check AWS service health
  • SSM agent not responding: Instance may need reboot or SSM agent reinstall
  • Startup timeout: Increase connection timeout, check instance logs

Permission denied errors

# Check IAM permissions
aws iam get-user --profile your-profile
aws iam list-attached-user-policies --user-name your-username --profile your-profile

Required permissions:

  • ssm:StartSession
  • ssm:DescribeInstanceInformation
  • ec2:DescribeInstances
  • ec2:StartInstances
  • ec2-instance-connect:SendSSHPublicKey

Region mismatch issues

# Check profile region
aws configure get region --profile your-profile

# Check instance region
aws ec2 describe-instances --instance-ids i-1234567890abcdef0 --profile your-profile --query 'Reservations[0].Instances[0].Placement.AvailabilityZone'

Solution: Ensure AWS profile region matches instance region.

SSH Key Issues

Key authentication failures

# Check SSH key permissions
ls -la ~/.ssh/vscode/
chmod 600 ~/.ssh/vscode/your-key      # Private key
chmod 644 ~/.ssh/vscode/your-key.pub  # Public key

# Test SSH key format
ssh-keygen -l -f ~/.ssh/vscode/your-key.pub

1Password integration issues

# Check 1Password CLI
op account list
op item list --categories "SSH Key"

# Check SSH agent
ssh-add -l
echo $SSH_AUTH_SOCK
ls -la ~/.1password/agent.sock

Common 1Password issues:

  • Agent not running: Enable SSH agent in 1Password settings
  • Keys not visible: Check vault permissions and SSH category
  • Wrong vault: Ensure vault is enabled for SSH in 1Password settings
  • CLI authentication expired: Run op signin to re-authenticate

Key naming and discovery issues

# Check for correct key naming in 1Password
op item list --categories "SSH Key" | grep "cloudX SSH Key"

Solution: Ensure keys follow naming convention "cloudX SSH Key - {keyname}".

Network and Connectivity Issues

SSM Session Problems

"Invalid session" errors

# Check SSM agent on instance
aws ssm send-command \
    --document-name "AWS-RunShellScript" \
    --parameters 'commands=["sudo systemctl status amazon-ssm-agent"]' \
    --targets "Key=InstanceIds,Values=i-1234567890abcdef0" \
    --profile your-profile

Tunnel establishment failures

# Test direct SSM session
aws ssm start-session --target i-1234567890abcdef0 --profile your-profile

# Check Session Manager plugin logs (varies by OS)
# macOS/Linux: ~/.aws/sessionmanagerplugin/logs/
# Windows: %USERPROFILE%\.aws\sessionmanagerplugin\logs\

Network Configuration Issues

VPC and subnet configuration

Requirements:

  • Instance must be in subnet with internet access (for SSM communication)
  • Security groups don't need SSH inbound rules (SSM uses outbound HTTPS)
  • VPC must have SSM VPC endpoints OR internet gateway

Corporate firewall/proxy issues

Common problems:

  • Outbound HTTPS (443) blocked to AWS services
  • Proxy configuration not applied to AWS CLI
  • Certificate validation issues

Solutions:

# Configure AWS CLI for proxy
aws configure set http_proxy http://proxy.company.com:8080
aws configure set https_proxy https://proxy.company.com:8080

# Skip SSL verification (not recommended for production)
aws configure set ca_bundle ""

Advanced Troubleshooting

Debug Mode

Enable verbose logging for deeper diagnosis:

# Enable SSH debugging
export SSH_DEBUG=1
ssh -vvv cloudx-dev-myserver

# Enable AWS CLI debugging  
export AWS_DEBUG=1
uvx cloudx-proxy connect i-1234567890abcdef0 22 --profile your-profile

Log File Locations

SSH logs

  • Linux/macOS: /var/log/auth.log or journalctl -u ssh
  • Windows: Event Viewer → Windows Logs → System

AWS CLI logs

  • Session Manager plugin logs in ~/.aws/sessionmanagerplugin/logs/
  • CloudTrail for API call history

VSCode logs

  • Help → Toggle Developer Tools → Console tab
  • Look for "Remote-SSH" extension logs

Configuration Validation

SSH configuration testing

# Test SSH config syntax
ssh -F ~/.ssh/vscode/config -T cloudx-dev-myserver

# Verbose SSH connection test
ssh -F ~/.ssh/vscode/config -vvv cloudx-dev-myserver echo "test"

# Test ProxyCommand directly
uvx cloudx-proxy connect i-1234567890abcdef0 22 --profile your-profile

AWS configuration testing

# Test full connection flow
aws sts get-caller-identity --profile your-profile
aws ec2 describe-instances --instance-ids i-1234567890abcdef0 --profile your-profile  
aws ssm describe-instance-information --instance-information-filter-list key=InstanceIds,valueSet=i-1234567890abcdef0 --profile your-profile

Getting Help

Information to Gather

When reporting issues, include:

  1. Environment information:

    python --version
aws --version  
uvx --version
uname -a  # Linux/macOS
systeminfo | findstr OS  # Windows

  2. Configuration details:

    uvx cloudx-proxy list --detailed
aws configure list --profile your-profile

  3. Error messages:

    • Complete error output (not just summary)
    • VSCode developer console errors
    • SSH verbose output (ssh -vvv)

  4. Steps to reproduce:

    • Exact commands run
    • Expected vs actual behavior
    • When the issue started occurring

Support Channels

For common solutions, also check the FAQ page.

Clone this wiki locally