Troubleshooting Guide

Installation Issues

Command not found after installation

Symptoms:

terraback: command not found

Solutions:

1. Verify pip installation location:

pip show terraback

2. Check if the install location is in PATH:

# Find where pip installs scripts
python -m site --user-base

# Add to PATH if needed (Linux/macOS)
export PATH=$PATH:$(python -m site --user-base)/bin

3. Try reinstalling:

pip uninstall terraback
pip install terraback

Python version error

Symptoms:

Error: Python 3.8 or higher required

Solution: Install Python 3.8+ from python.org or use pyenv:

pyenv install 3.11
pyenv global 3.11
pip install terraback

Permission denied during installation

Symptoms:

Error: Permission denied

Solutions:

# Option 1: Use virtual environment (recommended)
python -m venv terraback-env
source terraback-env/bin/activate
pip install terraback

# Option 2: Install for user only
pip install --user terraback

Authentication Issues

AWS credentials not found

Symptoms:

Error: Unable to locate credentials

Solutions:

1. Configure AWS CLI:

aws configure

2. Or set environment variables:

export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_DEFAULT_REGION="us-east-1"

3. Verify credentials:

aws sts get-caller-identity

Azure authentication failed

Symptoms:

Error: Azure authentication failed

Solutions:

1. Login with Azure CLI:

az login

2. Or use service principal:

export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"
export AZURE_TENANT_ID="your-tenant-id"
export AZURE_SUBSCRIPTION_ID="your-subscription-id"

3. Verify authentication:

az account show

GCP authentication failed

Symptoms:

Error: GCP authentication failed

Solutions:

1. Login with gcloud:

gcloud auth application-default login

2. Or use service account:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

3. Verify authentication:

gcloud auth list

Scanning Issues

No resources found

Symptoms:

No resources found in region us-east-1

Solutions:

1. Verify you're scanning the correct region:

# Check which regions have resources
aws ec2 describe-instances --query 'Reservations[].Instances[].Placement.AvailabilityZone'

2. Check permissions - you need read access:

# AWS: Ensure you have ReadOnlyAccess or equivalent
aws iam get-user

3. Try scanning a specific service:

terraback aws s3 scan --output-dir ./output  # S3 is global

Permission denied during scan

Symptoms:

Error: Access Denied when calling DescribeInstances

Solutions:

1. Check IAM permissions:

aws iam list-attached-user-policies --user-name your-username

2. Ensure you have at least ReadOnlyAccess policy or equivalent permissions for the services you're scanning.

3. For specific services, check the required permissions in AWS documentation.

API rate limiting / throttling

Symptoms:

Error: Rate exceeded
Error: Throttling

Solutions:

1. Reduce parallel workers:

terraback scan all aws -r us-east-1 --parallel 2 -o ./output

2. Enable caching to reduce API calls (caching is opt-in via --cache, off by default):

# First scan with --cache populates the cache
terraback scan all aws -r us-east-1 --cache -o ./output

# Subsequent scans with --cache reuse it (within the 60 minute TTL)
terraback scan all aws -r us-east-1 --cache -o ./output

3. Scan specific services instead of all:

terraback aws ec2 scan-instances -r us-east-1 -o ./output
terraback aws s3 scan -o ./output

Scan timeout

Symptoms:

Error: Operation timed out

Solutions:

1. Scan specific services instead of all resources
2. Reduce parallel workers
3. Try scanning during off-peak hours
4. Check network connectivity

License Issues

License activation failed

Symptoms:

Error: License activation failed
Error: Invalid license key

Solutions:

1. Verify license key format. Standard keys look like XXXX-XXXX-XXXX-XXXX; offline keys (v0.6.0+) use a different, longer Ed25519-signed format. terraback license activate auto-detects which one you have:

terraback license activate <your-key>

2. If you're using a standard key, check internet connectivity - standard activation requires online validation. Offline keys validate entirely locally and need no network access, so a connectivity error with an offline key points to a different problem — see step 3.

3. Verify you're using the correct license key from your email, and that it was not truncated or altered when copied.

4. Contact support if issue persists: contact@terraback.io

See Licensing for the two activation modes, and MCP Server: Licensing and Limits for offline-key details.

License not found

Symptoms:

Error: No valid license found
Feature requires Professional license

Solutions:

1. Check license status:

terraback license status

2. Re-activate if needed:

terraback license activate YOUR-LICENSE-KEY

3. License file location (depends on activation mode):
   • Standard (online) keys - Linux/macOS: ~/.terraback/license.jwt; Windows: %USERPROFILE%\.terraback\license.jwt
   • Offline keys (v0.6.0+) - ~/.terraback/license.key, or supplied via the TERRABACK_LICENSE environment variable

Output Issues

Generated Terraform has errors

Symptoms:

Error: Invalid resource configuration

Solutions:

1. Validate generated files:

cd ./output
terraform init
terraform validate

2. Check for missing dependencies - use --with-deps flag:

terraback aws ec2 scan-instances --with-deps -r us-east-1 -o ./output

3. Review generated code for any cloud-specific issues

Import fails

Symptoms:

Error: Resource already managed by Terraform
Error: Cannot import non-existent resource

Solutions:

1. Ensure resource exists in cloud:

aws ec2 describe-instances --instance-ids i-1234567890abcdef0

2. Check if resource is already in state:

terraform state list

3. Remove from state if re-importing:

terraform state rm aws_instance.example
terraform import aws_instance.example i-1234567890abcdef0

Cache Issues

Stale data in scans

Symptoms: Resources showing old configurations or deleted resources still appearing.

Solutions:

1. Clear the cache:

terraback cache clear

2. Invalidate specific service cache:

terraback cache invalidate --service ec2

3. Check cache statistics:

terraback cache stats

Debug Mode

Enable verbose logging

# Set environment variables
export TERRABACK_LOG_LEVEL=DEBUG
export TERRABACK_LOG_FILE=/tmp/terraback.log

# Or use verbose flag
terraback aws ec2 scan-instances -v -r us-east-1 -o ./output

View debug logs

# Check log file
cat /tmp/terraback.log

# Or use tail for live viewing
tail -f /tmp/terraback.log

Getting Help

Before contacting support

1. Verify authentication:

terraback scan auth-check

2. Enable debug logging and capture the error

3. Note the specific command and error message

Support channels

• Documentation: docs.terraback.io
• Email: contact@terraback.io — report bugs and request features

Information to include

When reporting issues, include:

• Python version (python --version)
• Operating system
• Cloud provider and service
• Full error message
• Steps to reproduce