Troubleshooting Guide

View on GitHub

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

  2. Check source path contains .tf files:

    ls -la /path/to/terraform/*.tf

  3. Ensure Terraform can initialize:

    terraform init

  4. 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

--show doesn't open the diagram on WSL

Problem: Running TerraVision under Windows Subsystem for Linux with --show, the diagram is generated successfully but no viewer opens. You may also see an error from xdg-open about no application being registered for the file type, or a warning that says WSL detected but wslview is not installed.

Cause: WSL ships without a Linux desktop database, so the standard xdg-open resolver has no .desktop files to consult and can't pick a handler.

Solution: Install the wslu package, which provides wslview — a tool that delegates the open back to Windows so the host's file associations are used:

sudo apt install wslu

TerraVision automatically detects WSL at runtime and routes --show through wslview once it's available; no further configuration is needed. The diagram itself is always generated correctly regardless — --show only controls auto-opening.

If you'd rather not install wslu, omit --show and open the output file from Windows Explorer (everything under \\wsl$\<distro>\... is reachable from Windows) or directly from your IDE.

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

  2. Check if resources are conditionally created:

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

  3. Verify workspace:

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

  4. 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

  2. Use different output format:

    terravision draw --source . --format svg

  3. 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

  2. Add connections via annotations:

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

  3. Enable debug mode to see connection processing:

    terravision draw --source . --debug

AI Refinement Issues

"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 the configured model is installed (default is llama3 —
# whatever you set in OLLAMA_MODEL inside cloud_config_<provider>.py)
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"

  2. Check API Gateway is deployed:

    cd ai-backend-terraform
terraform output api_endpoint

  3. 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

  2. Use simplified mode:

    terravision draw --source . --simplified

  3. Use specific workspace to reduce scope:

    terravision draw --source . --workspace production

  4. 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

  2. Use simplified mode:

    terravision draw --source . --simplified

  3. 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'))"

  3. Verify resource names exist:

    terravision graphdata --source . --show_services

  4. 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

  2. Check authentication:

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

  3. 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

Include in Bug Reports

  1. TerraVision version: terravision --version
  2. Python version: python --version
  3. Terraform version: terraform version
  4. Operating system
  5. Debug output: terravision draw --debug
  6. 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:

  1. Enable debug mode and save output:

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

  2. Create minimal example that reproduces the issue

  3. Open GitHub issue with:

    • Debug log
    • Minimal example
    • System information
    • Steps to reproduce

We're here to help! 🚀