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:

# 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:

# Add to .env file
SGO_PORT=8080

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

Option 2 - Find and stop conflicting service:

# 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:

   cat .env
   # Should show: AWS_CONFIG_PATH=/home/yourusername/.aws
   

2. Create .env file if missing:

   cat > .env << EOF
   AWS_CONFIG_PATH=$HOME/.aws
   PUID=$(id -u)
   PGID=$(id -g)
   EOF
   

3. Verify AWS files exist on host:

   ls -la ~/.aws/
   # Should show: config, credentials
   

4. Check file permissions:

   chmod 600 ~/.aws/credentials
   chmod 644 ~/.aws/config
   

5. Rebuild container:

   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:

   cat > .env << EOF
   AWS_CONFIG_PATH=$HOME/.aws
   PUID=$(id -u)
   PGID=$(id -g)
   EOF
   

2. If using local directory mode, fix ownership:

   sudo chown -R $(id -u):$(id -g) ./data
   

3. Or switch to Docker volume mode (default):

   # 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:

   docker-compose down
   

2. If using local directory mode, remove lock file:

   rm -f ./data/aws_export.db-journal
   

3. If problem persists, use Docker volume mode:

   # 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:

   docker-compose logs -f
   

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

3. Try running in debug mode:

   # 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:

   cat ~/.aws/config
   

2. Ensure profiles are properly formatted:

   [profile my-profile]
   region = us-west-2
   
   [default]
   region = us-east-1
   

3. Check file permissions:

   chmod 644 ~/.aws/config
   

4. Restart container to reload profiles:

   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:

   [profile my-profile]
   region = us-west-2
   mfa_serial = arn:aws:iam::123456789012:mfa/username
   

3. Verify credentials are valid:

   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)

2. Test permissions with AWS CLI:

   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:

   [profile my-profile]
   region = us-west-2  # Ensure this is correct
   

2. Remember: EC2 resources are region-specific

3. Try specifying region explicitly:

   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:

   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:

   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:

   # 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:

   # Fedora
   sudo dnf install podman-compose
   
   # Ubuntu/Debian
   pip3 install podman-compose
   

2. Use docker command instead:

   # Podman supports docker CLI
   alias docker=podman
   docker-compose up --build
   

3. Check SELinux contexts (Fedora/RHEL):

   # 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:

   docker-compose logs -f
   

2. Enable debug mode (see Configuration)

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