Terraform Module Resource Cycle Debugger

Threat/Impact Level: HIGH | Downtime Risk: HIGH | Time to Fix: 15–45 mins

TL;DR

• What broke: Terraform's DAG (Directed Acyclic Graph) resolver detected a circular reference — resource A depends on module B, and module B depends on resource A, creating an unresolvable execution order.
• How to fix it: Identify the circular reference chain using terraform graph | dot -Tsvg, then break the cycle by extracting shared values into locals/variables, removing implicit depends_on chains, or restructuring module outputs.
• Fast path: Use our Client-Side Sandbox above to auto-refactor this — paste your failing .tf files and get a dependency-safe rewrite without sending your state or secrets anywhere.

Error: Cycle in dependency graph

Cycle: module.networking.aws_security_group.this, aws_instance.app, module.networking

Terraform detected a cycle in the dependency graph. This means Terraform
cannot determine the correct order in which to create, update, or destroy
resources. The cycle must be broken before Terraform can proceed.

How to Fix It

Step 0: Visualize the Cycle First

# Requires graphviz installed
terraform graph 2>&1 | grep -A 20 'Cycle'

# Full visual graph — open cycle.svg in a browser
terraform graph | dot -Tsvg > cycle.svg

The terraform graph output will show you the exact node names forming the cycle. Do not guess — read the graph.

Basic Fix: Break the Implicit Dependency

The most common cause is a resource outside a module using depends_on pointing to a module, while that module internally references an output from that same resource.

# main.tf — BROKEN: aws_instance depends on module.networking,
# but module.networking takes aws_instance.app.id as a variable input

- resource "aws_instance" "app" {
-   ami           = "ami-0abcdef1234567890"
-   instance_type = "t3.medium"
-   subnet_id     = module.networking.subnet_id
-
-   depends_on = [module.networking]  # <-- explicit depends_on creates the cycle
- }
-
- module "networking" {
-   source      = "./modules/networking"
-   instance_id = aws_instance.app.id  # <-- module needs instance ID = cycle
- }

+ # FIX: Decouple by removing the circular variable.
+ # If networking needs the instance ID for a security group rule,
+ # create that rule OUTSIDE the module, after the instance exists.
+
+ resource "aws_instance" "app" {
+   ami           = "ami-0abcdef1234567890"
+   instance_type = "t3.medium"
+   subnet_id     = module.networking.subnet_id
+   # depends_on removed — implicit dependency via subnet_id attribute reference is sufficient
+ }
+
+ module "networking" {
+   source = "./modules/networking"
+   # instance_id removed from module inputs
+ }
+
+ # Security group rule that needed instance_id now lives at root scope
+ resource "aws_security_group_rule" "allow_app" {
+   type              = "ingress"
+   from_port         = 8080
+   to_port           = 8080
+   protocol          = "tcp"
+   security_group_id = module.networking.app_sg_id
+   source_security_group_id = aws_instance.app.security_groups[0]  # reference is safe here
+ }

Enterprise Best Practice: Restructure with Layered Module Architecture

The root cause of most module cycles is over-coupling — a module trying to both create infrastructure AND consume outputs from resources it's supposed to precede. The fix is a layered dependency pattern: split into foundation, compute, and policy layers with clean unidirectional data flow.

# ANTI-PATTERN: Single monolithic module with bidirectional references
- module "app_stack" {
-   source       = "./modules/app_stack"
-   vpc_id       = aws_vpc.main.id
-   instance_arn = aws_instance.app.arn  # app_stack creates the instance AND needs its ARN
- }

# ENTERPRISE FIX: Three-layer separation
# Layer 1 — Network (no compute dependencies)
+ module "network" {
+   source = "./modules/network"
+   vpc_cidr = var.vpc_cidr
+ }
+
# Layer 2 — Compute (depends on network outputs only)
+ module "compute" {
+   source    = "./modules/compute"
+   subnet_id = module.network.private_subnet_id
+   sg_id     = module.network.app_sg_id
+ }
+
# Layer 3 — Policy/IAM (consumes compute outputs, no circular refs)
+ module "iam_bindings" {
+   source       = "./modules/iam_bindings"
+   instance_arn = module.compute.instance_arn
+   role_name    = module.compute.iam_role_name
+ }

Key rules for the enterprise pattern:

• Module outputs flow downward only (network → compute → policy).
• No module at layer N may accept an input from a module at layer N or above.
• Use locals to compose values from multiple modules at root scope — never pass them back into a module that was already in the chain.
• If two resources genuinely need each other (e.g., two security groups with mutual ingress rules), use aws_security_group_rule resources at root scope rather than embedding rules inside the aws_security_group resource block — this is also the AWS-recommended pattern to avoid the same cycle in the provider itself.

# Security group self-referencing cycle — common AWS pattern mistake
- resource "aws_security_group" "app" {
-   name   = "app-sg"
-   vpc_id = var.vpc_id
-
-   ingress {
-     from_port       = 0
-     to_port         = 0
-     protocol        = "-1"
-     security_groups = [aws_security_group.db.id]  # cycle if db references app
-   }
- }

+ resource "aws_security_group" "app" {
+   name   = "app-sg"
+   vpc_id = var.vpc_id
+   # No inline ingress/egress rules — defined separately below
+ }
+
+ resource "aws_security_group_rule" "app_from_db" {
+   type                     = "ingress"
+   from_port                = 0
+   to_port                  = 0
+   protocol                 = "-1"
+   security_group_id        = aws_security_group.app.id
+   source_security_group_id = aws_security_group.db.id
+ }

💡 Tired of pasting proprietary infrastructure configs into public LLMs? Generic AI interfaces log your company's ARNs, connection strings, and private keys. StackEngine enforces client-side zero-trust boundaries—the sandbox above executes 100% locally in your browser. Drop your broken manifest above to redact secrets locally and synthesize deterministic patch drafts with your own API key.

(For CI/CD pipeline automation, install via npm i -g stackengine).

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.83.5
    hooks:
      - id: terraform_validate
      - id: terraform_tflint

# .tflint.hcl
plugin "terraform" {
  enabled = true
  preset  = "recommended"  # includes module structure checks
}

# policies/no_module_cycles.rego
package terraform.module_cycles

# Deny any module variable input that references an output
# from a resource that the same module creates
deny[msg] {
  module_call := input.configuration.root_module.module_calls[name]
  some key
  val := module_call.expressions[key]
  # Check if the expression references a resource managed by this module
  contains(val.references[_], concat(".", ["module", name]))
  msg := sprintf(
    "Module '%s' input '%s' creates a circular reference back to itself.",
    [name, key]
  )
}

terraform show -json plan.tfplan | conftest test --policy ./policies -

checkov -d . --check CKV_TF_1 --framework terraform
# CKV_TF_1 enforces module source pinning which indirectly prevents
# unpinned module versions introducing new cyclic dependencies silently

# .github/workflows/tf-validate.yml
name: Terraform Graph Validation
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "~1.7"
      - run: terraform init -backend=false
      - run: terraform validate
      - run: terraform graph > /dev/null  # exits non-zero if cycle detected
        name: Graph cycle check