SGO/wiki/Troubleshooting.md

# Troubleshooting

## Container Issues

### Cannot Connect to Docker Daemon

**Error**: `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`

**Solution**:
```bash
# Linux: Start Docker service
sudo systemctl start docker
sudo systemctl enable docker  # Start on boot

# macOS/Windows: Open Docker Desktop application
# Ensure Docker Desktop is running in system tray
```

### Port Already in Use

**Error**: `Bind for 0.0.0.0:5000 failed: port is already allocated`

**Solution**:

Option 1 - Use different port:
```bash
# Add to .env file
SGO_PORT=8080

# Restart container
docker-compose down && docker-compose up
```

Option 2 - Find and stop conflicting service:
```bash
# Linux/macOS: Find process using port 5000
sudo lsof -i :5000
sudo kill -9 <PID>

# Windows: Find process using port 5000
netstat -ano | findstr :5000
taskkill /PID <PID> /F
```

### AWS Credentials Not Found in Container

**Error**: `AWS config file not found` or `Permission denied: '/home/sgo/.aws/config'`

**Solution**:

1. Verify `.env` file exists and contains `AWS_CONFIG_PATH`:
   ```bash
   cat .env
   # Should show: AWS_CONFIG_PATH=/home/yourusername/.aws
   ```

2. Create `.env` file if missing:
   ```bash
   cat > .env << EOF
   AWS_CONFIG_PATH=$HOME/.aws
   PUID=$(id -u)
   PGID=$(id -g)
   EOF
   ```

3. Verify AWS files exist on host:
   ```bash
   ls -la ~/.aws/
   # Should show: config, credentials
   ```

4. Check file permissions:
   ```bash
   chmod 600 ~/.aws/credentials
   chmod 644 ~/.aws/config
   ```

5. Rebuild container:
   ```bash
   docker-compose down && docker-compose up --build
   ```

### Permission Denied Errors

**Error**: `PermissionError: [Errno 13] Permission denied: '/app/data/aws_export.db'`

**Solution**:

1. Set PUID/PGID to match your user:
   ```bash
   cat > .env << EOF
   AWS_CONFIG_PATH=$HOME/.aws
   PUID=$(id -u)
   PGID=$(id -g)
   EOF
   ```

2. If using local directory mode, fix ownership:
   ```bash
   sudo chown -R $(id -u):$(id -g) ./data
   ```

3. Or switch to Docker volume mode (default):
   ```bash
   # Use default docker-compose.yml
   docker-compose down -v
   docker-compose up --build
   ```

### Database Locked Error

**Error**: `database is locked` or `OperationalError: database is locked`

**Solution**:

1. Stop all running containers:
   ```bash
   docker-compose down
   ```

2. If using local directory mode, remove lock file:
   ```bash
   rm -f ./data/aws_export.db-journal
   ```

3. If problem persists, use Docker volume mode:
   ```bash
   # Edit docker-compose.yml to use volume instead of bind mount
   docker-compose up --build
   ```

### Container Keeps Restarting

**Error**: Container exits immediately or restarts constantly

**Solution**:

1. Check container logs:
   ```bash
   docker-compose logs -f
   ```

2. Look for error messages in logs and address specific issues

3. Try running in debug mode:
   ```bash
   # Add to .env
   DEBUG=true

   docker-compose down && docker-compose up
   ```

## AWS Configuration Issues

### No AWS Profiles Found

**Error**: "No AWS profiles found" or empty profile list

**Solution**:

1. Verify `~/.aws/config` exists:
   ```bash
   cat ~/.aws/config
   ```

2. Ensure profiles are properly formatted:
   ```ini
   [profile my-profile]
   region = us-west-2

   [default]
   region = us-east-1
   ```

3. Check file permissions:
   ```bash
   chmod 644 ~/.aws/config
   ```

4. Restart container to reload profiles:
   ```bash
   docker-compose restart
   ```

### MFA Authentication Fails

**Error**: "MFA authentication failed" or "Invalid MFA code"

**Solution**:

1. Verify MFA code is current:
   - MFA codes expire every 30 seconds
   - Generate a fresh code and try again

2. Check `mfa_serial` is correct in `~/.aws/config`:
   ```ini
   [profile my-profile]
   region = us-west-2
   mfa_serial = arn:aws:iam::123456789012:mfa/username
   ```

3. Verify credentials are valid:
   ```bash
   aws sts get-caller-identity --profile my-profile
   ```

4. Ensure MFA device is active in AWS IAM Console

5. Check for clock skew:
   - Ensure system time is accurate
   - MFA is time-based and requires synchronized clocks

### Import Fails with Access Denied

**Error**: "Access Denied" or "UnauthorizedOperation"

**Solution**:

1. Verify IAM permissions (see [AWS Configuration](AWS-Configuration.md#required-iam-permissions))

2. Test permissions with AWS CLI:
   ```bash
   aws ec2 describe-instances --profile my-profile --max-results 1
   aws ec2 describe-security-groups --profile my-profile --max-results 1
   ```

3. Check if credentials have expired:
   - Temporary credentials expire
   - Try refreshing credentials

4. Verify you're using the correct profile

### Wrong Region / No Resources Found

**Error**: Import succeeds but no EC2/SG data appears

**Solution**:

1. Check region in profile configuration:
   ```ini
   [profile my-profile]
   region = us-west-2  # Ensure this is correct
   ```

2. Remember: EC2 resources are region-specific

3. Try specifying region explicitly:
   ```bash
   aws ec2 describe-instances --profile my-profile --region us-west-2
   ```

4. Import from correct region in profile

## Application Issues

### Search Returns No Results

**Problem**: Search box doesn't show any results

**Solution**:

1. Verify data was imported successfully:
   - Check import progress logs
   - Look for "Import complete" messages

2. Try different search terms:
   - Minimum 2 characters required
   - Try searching for "*" to see all resources

3. Check filter buttons:
   - Ensure you're not filtering out the type you're searching for
   - Try "All Resources" button

4. Refresh the page:
   ```
   Ctrl+F5 or Cmd+Shift+R
   ```

### Blank Page or UI Not Loading

**Problem**: Browser shows blank page or incomplete UI

**Solution**:

1. Check browser console for JavaScript errors:
   - Press F12 to open developer tools
   - Look at Console tab for errors

2. Clear browser cache and reload:
   ```
   Ctrl+Shift+R (Windows/Linux)
   Cmd+Shift+R (macOS)
   ```

3. Try a different browser

4. Check if application is running:
   ```bash
   docker-compose logs
   ```

### CSV Export Not Working

**Problem**: Export button doesn't download file

**Solution**:

1. Check browser popup blocker settings

2. Look for downloads in browser's download location

3. Try different browser

4. Check browser console for JavaScript errors (F12)

### Session Expired / MFA Required Again

**Problem**: Asked for MFA again before 55 minutes

**Solution**:

- AWS sessions expire after 1 hour (we cache for 55 minutes)
- This is expected behavior for security
- Simply enter MFA code again to create new session

## Performance Issues

### Slow Import

**Problem**: Import takes a very long time

**Solution**:

1. **Use parallel imports**:
   - Select all profiles at once
   - Click "Start Import" on each profile
   - All imports run simultaneously

2. **Check network connectivity to AWS**:
   ```bash
   ping ec2.us-west-2.amazonaws.com
   ```

3. **Large accounts take longer**:
   - Many EC2 instances/security groups increase import time
   - This is normal

### Slow Search

**Problem**: Search is laggy or slow

**Solution**:

1. **Large datasets**:
   - Thousands of resources can slow search
   - This is a known limitation of client-side search

2. **Use more specific search terms**:
   - Narrow down results with longer search strings

3. **Use regex carefully**:
   - Complex regex patterns can be slow
   - Disable regex for simple searches

## Platform-Specific Issues

### Windows

**Problem**: Path issues or permission errors

**Solution**:

1. Use WSL2 for better compatibility:
   ```powershell
   # Install WSL2 and run commands from Linux environment
   wsl --install
   ```

2. Use Git Bash for running commands

3. Ensure Docker Desktop is using WSL2 backend

4. Use forward slashes in paths

### macOS

**Problem**: Docker can't access files in home directory

**Solution**:

1. Open Docker Desktop Settings
2. Go to Resources → File Sharing
3. Add your home directory to shared paths
4. Click "Apply & Restart"

### Linux (Podman)

**Problem**: `podman-compose` not found or issues

**Solution**:

1. Install podman-compose:
   ```bash
   # Fedora
   sudo dnf install podman-compose

   # Ubuntu/Debian
   pip3 install podman-compose
   ```

2. Use `docker` command instead:
   ```bash
   # Podman supports docker CLI
   alias docker=podman
   docker-compose up --build
   ```

3. Check SELinux contexts (Fedora/RHEL):
   ```bash
   # Already handled by :z flag in docker-compose.yml
   # If issues persist, try:
   sudo setenforce 0  # Temporarily permissive mode for testing
   ```

## Getting Help

If you continue to experience issues:

1. **Check application logs**:
   ```bash
   docker-compose logs -f
   ```

2. **Enable debug mode** (see [Configuration](Configuration.md#example-4-debug-mode))

3. **Open an issue** on the repository with:
   - Error messages from logs
   - Steps to reproduce
   - Your environment (OS, Docker/Podman version)
   - Relevant configuration (sanitized)

4. **Check existing issues** - Your problem may already be solved