Troubleshooting Guide¶

Common Issues¶

Installation Issues¶

"terraform command not found"¶

Problem: Terraform is not installed or not in PATH

Solution:

# Verify Terraform installation
terraform version

# If not installed, install Terraform
# macOS
brew install terraform

# Ubuntu/Debian
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform

"dot command not found"¶

Problem: Graphviz is not installed

Solution:

# macOS
brew install graphviz

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install graphviz

# Windows
# Download from https://graphviz.org/download/

# Verify installation
dot -V

"Terraform version not supported"¶

Problem: Terraform version is too old

Solution:

# Check current version
terraform version

# TerraVision requires Terraform v1.0.0 or higher
# Upgrade Terraform
brew upgrade terraform  # macOS
# Or download latest from https://developer.hashicorp.com/terraform/downloads

Python Version Issues¶

Problem: Python 3.10+ not available

Solution:

# Check Python version
python --version

# Install Python 3.10+
# macOS
brew install python@3.10

# Ubuntu
sudo apt-get install python3.10

# Install TerraVision with a specific Python version
python3.10 -m pip install terravision

Terraform Enterprise / Remote Backend Issues¶

"Backend configuration changed" or "State locked"¶

Problem: TerraVision conflicts with Terraform Enterprise remote backend

Explanation: TerraVision automatically forces local backend execution to generate complete infrastructure diagrams (not just state deltas). This is intentional and required for accurate visualization.

How it works: - TerraVision copies terravision_override.tf to your source directory - This forces backend "local" configuration - Terraform ignores remote state and shows all resources - Your actual TFE state remains unchanged

Solution: This is expected behavior - no action needed. TerraVision will: 1. Temporarily override your backend configuration 2. Generate a fresh plan showing all resources 3. Create the diagram from the complete infrastructure definition 4. Leave your remote state untouched

Note: If you see terravision_override.tf in your directory after running TerraVision, you can safely delete it or add to .gitignore.

"TFE_TOKEN required for module registry"¶

Problem: Private Terraform Enterprise module registry requires authentication

Solution:

# Set TFE token for private module access
export TFE_TOKEN="your-tfe-token"

# Generate token from TFE UI:
# Settings > Tokens > Create an API token

# Or use .terraformrc credentials
cat ~/.terraformrc
# credentials "app.terraform.io" {
#   token = "your-token"
# }

Note: TFE_TOKEN is only needed for accessing private module registries, not for basic diagram generation.

Runtime Issues¶

"No resources found"¶

Problem: TerraVision can't find Terraform resources

Checklist: 1. Verify Terraform code is valid:

cd /path/to/terraform
terraform init
terraform validate
terraform plan

Check source path contains .tf files:
```
ls -la /path/to/terraform/*.tf
```
Ensure Terraform can initialize:
```
terraform init
```

Try with debug mode:

terravision draw --source /path/to/terraform --debug

"Module not found" or "Module download failed"¶

Problem: Terraform modules can't be downloaded

Solution:

# Clear Terraform cache
rm -rf .terraform/

# Clear TerraVision cache
rm -rf ~/.terravision/

# Re-initialize
terraform init

# Try again
terravision draw --source /path/to/terraform

"Permission denied" errors when installing¶

Problem: pip install terravision fails with permission errors (common on system Python without sudo)

Solution — use an isolated install so sudo is never required:

# Preferred: pipx (fully isolated, auto-manages PATH)
pipx install terravision

# Or user install
pip install --user terravision

# Or inside a virtualenv
python -m venv venv
source venv/bin/activate
pip install terravision

Pre-Generated Plan File Issues¶

"This appears to be a binary Terraform plan file"¶

Problem: You passed a binary .tfplan file instead of JSON

Solution: Convert the binary plan to JSON first:

terraform show -json tfplan.bin > plan.json
terravision draw --planfile plan.json --graphfile graph.dot --source ./path-to-your-terraform

"Plan file does not contain 'resource_changes'"¶

Problem: The JSON file is not a valid Terraform plan output

Solution: Ensure you use terraform show -json to export the plan:

terraform plan -out=tfplan.bin
terraform show -json tfplan.bin > plan.json

Do not use terraform plan -json (streaming output) — use terraform show -json on a saved plan file.

"Plan file contains no resource changes"¶

Problem: The Terraform plan has no resources to create, update, or destroy

Solution: Verify that terraform plan shows resources:

terraform plan
# Should show resources to create/update/destroy

If no resources appear, check your Terraform code and variable files.

"--planfile requires --graphfile and --source"¶

Problem: You must provide all three options together

Solution: Always provide --planfile, --graphfile, and --source:

terravision draw \
  --planfile plan.json \
  --graphfile graph.dot \
  --source ./path-to-your-terraform

"WARNING: --workspace/--varfile ignored with --planfile"¶

Problem: These options are irrelevant when using pre-generated plan files

Explanation: When you provide a --planfile, TerraVision skips Terraform execution entirely. The workspace and variable file were already applied when the plan was originally generated. This warning is informational — your diagram will still be generated correctly.

Diagram Generation Issues¶

Empty or Incomplete Diagrams¶

Problem: Diagram is generated but shows no resources or is incomplete

Checklist: 1. Run Terraform plan to ensure resources exist:

terraform plan

Check if resources are conditionally created:

# Use appropriate variable files
terravision draw --source . --varfile prod.tfvars

Verify workspace:

# Use correct workspace
terravision draw --source . --workspace production

Enable debug mode:

terravision draw --source . --debug
# Check tfdata.json for parsed resources

Diagram Layout Issues¶

Problem: Resources are overlapping or poorly positioned

Solutions: 1. Try simplified mode:

terravision draw --source . --simplified

Use different output format:

terravision draw --source . --format svg

Use annotations to adjust layout:

# terravision.yml
remove:
  - aws_iam_role.*  # Remove noisy resources

Missing Connections¶

Problem: Expected connections between resources are not shown

Solutions: 1. Check if resources are actually connected in Terraform:

terraform show

Add connections via annotations:

# terravision.yml
connect:
  aws_lambda_function.api:
    - aws_rds_cluster.db: "Database queries"

Enable debug mode to see connection processing:
```
terravision draw --source . --debug
```

"Cannot reach Ollama server"¶

Problem: Ollama server is not running or not accessible

Solution:

# Check if Ollama is running
curl http://localhost:11434/api/tags

# If not running, start Ollama
ollama serve

# If port is in use, kill existing process
lsof -ti:11434 | xargs kill -9
ollama serve

# Verify llama3 model is installed
ollama list
ollama pull llama3

"Ollama model not loaded"¶

Problem: Model unloads too quickly

Solution:

# Extend keep-alive time (default is 5 minutes)
export OLLAMA_KEEP_ALIVE=1h

# Restart Ollama
ollama serve

"Bedrock API error"¶

Problem: AWS Bedrock API is not configured or accessible

Solution: 1. Verify API endpoint in modules/cloud_config.py:

BEDROCK_API_ENDPOINT = "https://your-api-id.execute-api.us-east-1.amazonaws.com/prod/chat"

Check API Gateway is deployed:

cd ai-backend-terraform
terraform output api_endpoint

Verify API is accessible:

curl -X POST https://your-api-endpoint/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "test"}'

AI Annotation Issues¶

"AI Annotations Look Wrong"¶

Problem: AI-generated labels, flows, or external actors are inaccurate or unhelpful.

Solution: Edit your terravision.yml to override specific AI suggestions. The user file always takes precedence over terravision.ai.yml:

# terravision.yml - your overrides
format: 0.2
title: "Correct Title Here"

connect:
  aws_lambda_function.api:
    - aws_rds_cluster.db: "Correct label here"

Any annotation you define in terravision.yml replaces the corresponding AI-generated value. Annotations you do not override continue to use the AI suggestions.

"AI Backend Unreachable"¶

Problem: Ollama server is down, or the Bedrock API endpoint is not accessible.

How TerraVision handles this: If the AI backend cannot be reached, TerraVision skips annotation generation and renders the diagram without AI annotations. The deterministic graph is never affected by AI availability -- you will always get a valid diagram.

To diagnose:

# Check Ollama is running
curl http://localhost:11434/api/tags

# Check Bedrock endpoint (replace with your API URL)
curl -X POST https://your-api-id.execute-api.us-east-1.amazonaws.com/prod/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "test"}'

If you have an existing terravision.ai.yml from a previous run, it will still be loaded and applied even when the backend is unreachable. Only the regeneration step is skipped.

Performance Issues¶

Slow Diagram Generation¶

Problem: TerraVision takes too long to generate diagrams

Solutions: 1. Export to JSON first, then generate multiple formats:

terravision graphdata --source . --outfile graph.json
terravision draw --source graph.json --format svg
terravision draw --source graph.json --format png

Use simplified mode:

terravision draw --source . --simplified

Use specific workspace to reduce scope:

terravision draw --source . --workspace production

Clear cache:
```
rm -rf ~/.terravision/
```

Large File Sizes¶

Problem: Generated diagrams are too large

Solutions: 1. Use SVG format (smaller and scalable):

terravision draw --source . --format svg

Use simplified mode:

terravision draw --source . --simplified

Remove unnecessary resources via annotations:

remove:
  - aws_iam_role.*
  - aws_cloudwatch_log_group.*

Annotation Issues¶

Annotations Not Applied¶

Problem: Annotations in terravision.yml are ignored

Checklist: 1. Verify file name is exactly terravision.yml 2. Check YAML syntax:

# Use online YAML validator or
python -c "import yaml; yaml.safe_load(open('terravision.yml'))"

Verify resource names exist:

terravision graphdata --source . --show_services

Enable debug mode:
```
terravision draw --source . --debug
```

Wildcards Not Matching¶

Problem: Wildcard patterns don't match expected resources

Solution:

# List all resources to verify patterns
terravision graphdata --source . --outfile resources.json
cat resources.json | jq 'keys'

# Test specific patterns
grep "aws_lambda" resources.json

Git Repository Issues¶

"Failed to clone repository"¶

Problem: Can't access Git repository

Solutions: 1. Verify repository URL:

git clone https://github.com/user/repo.git

Check authentication:

# For private repos, use SSH or token
git clone git@github.com:user/repo.git

Specify subfolder:

terravision draw --source https://github.com/user/repo.git//terraform/aws

"Module source not found"¶

Problem: Terraform modules in Git can't be accessed

Solution:

# Ensure Git credentials are configured
git config --global credential.helper store

# Or use SSH keys
ssh-add ~/.ssh/id_rsa

Debug Mode¶

Enable debug mode for detailed troubleshooting:

terravision draw --source /path/to/terraform --debug

Debug mode provides: - Detailed processing steps - Intermediate JSON files (tfdata.json) - Full error traces - Variable resolution details

Analyze debug output:

# Check parsed resources
cat tfdata.json | jq '.graphdict | keys'

# Check metadata
cat tfdata.json | jq '.meta_data'

# Check connections
cat tfdata.json | jq '.graphdict["aws_lambda_function.api"]'

Getting Help¶

Check Documentation¶

Command Help¶

terravision --help
terravision draw --help
terravision graphdata --help

Report Issues¶

GitHub Issues: https://github.com/patrickchugh/terravision/issues
Discussions: https://github.com/patrickchugh/terravision/discussions

Include in Bug Reports¶

TerraVision version: terravision --version
Python version: python --version
Terraform version: terraform version
Operating system
Debug output: terravision draw --debug
Minimal reproducible example

Quick Fixes¶

Reset Everything¶

# Clear all caches
rm -rf ~/.terravision/
rm -rf .terraform/
rm -f tfdata.json

# Reinstall TerraVision
pipx reinstall terravision         # if installed with pipx
# or: pip install --force-reinstall terravision

# Reinitialize Terraform
terraform init

# Try again
terravision draw --source . --debug

Verify Installation¶

# Check all dependencies
terraform version  # Should be v1.0.0+
python --version   # Should be 3.10+
dot -V            # Should show Graphviz version
git --version     # Should show Git version

# Test TerraVision
terravision --version
terravision --help

Still Having Issues?¶

If you've tried everything and still have problems:

Enable debug mode and save output:

terravision draw --source . --debug > debug.log 2>&1

Create minimal example that reproduces the issue
Open GitHub issue with:
Debug log
Minimal example
System information
Steps to reproduce

We're here to help! 🚀

Troubleshooting Guide¶

Common Issues¶

Installation Issues¶

"terraform command not found"¶

"dot command not found"¶

"Terraform version not supported"¶

Python Version Issues¶

Terraform Enterprise / Remote Backend Issues¶

"Backend configuration changed" or "State locked"¶

"TFE_TOKEN required for module registry"¶

Runtime Issues¶

"No resources found"¶

"Module not found" or "Module download failed"¶

"Permission denied" errors when installing¶

Pre-Generated Plan File Issues¶

"This appears to be a binary Terraform plan file"¶

"Plan file does not contain 'resource_changes'"¶

"Plan file contains no resource changes"¶

"--planfile requires --graphfile and --source"¶

"WARNING: --workspace/--varfile ignored with --planfile"¶

Diagram Generation Issues¶

Empty or Incomplete Diagrams¶

Diagram Layout Issues¶

Missing Connections¶

AI Refinement Issues¶

"Cannot reach Ollama server"¶

"Ollama model not loaded"¶

"Bedrock API error"¶

AI Annotation Issues¶

"AI Annotations Look Wrong"¶

"AI Backend Unreachable"¶

Performance Issues¶

Slow Diagram Generation¶

Large File Sizes¶

Annotation Issues¶

Annotations Not Applied¶

Wildcards Not Matching¶

Git Repository Issues¶

"Failed to clone repository"¶

"Module source not found"¶

Debug Mode¶

Getting Help¶

Check Documentation¶

Command Help¶

Report Issues¶

Include in Bug Reports¶

Quick Fixes¶

Reset Everything¶

Verify Installation¶

Still Having Issues?¶