criticalAdvancedSymptom-first#cycle#dependency#reference#graph

Dependency cycle — circular reference between resources

Error: Cycle: resource A -> resource B -> resource A

Likely source:configurationdeployment

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Error: Cycle: resource A -> resource B -> resource A
  • terraform plan fails with cycle error
  • Resource graph has circular dependency

Break cycles by using depends_on sparingly, extracting shared state to a data source, or restructuring the module boundary.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Cycle error message

    terraform plan 2>&1 | grep -A5 'Cycle'

  • Resource graph visualization

    terraform graph | dot -Tsvg > graph.svg

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • Resource A references resource B in an attribute
  • Resource B references resource A in the same or different attribute
  • terraform graph shows a cycle

Confirm before fixing

terraform graph | dot -Tsvg > graph.svg && open graph.svg
READ

Visualize the cycle in the dependency graph

Fix

terraform validate 2>&1 | grep 'Cycle'
READ

Confirm the cycle is resolved

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
terraform plan 2>&1 | grep -A10 'Cycle'
READ

Read the full cycle path

2
terraform graph | dot -Tsvg > graph.svg
READ

Visualize the dependency graph

3
grep -rn 'resource.*reference' --include='*.tf' .
READ

Find the circular reference in code

4
terraform validate
READ

Confirm the cycle is resolved after fixing

Prevention

  • Design resources with one-directional dependency flow (top-down).
  • Use data sources instead of resource references when possible.
  • Avoid depending on resources from the same module in outputs.
  • Visualize the graph periodically for complex infrastructures.

Related runbooks

Same stack, same failure family — worth a skim.

Unsupported argument — typo or misplaced attributemedium

An argument named "instance_typo" is not expected here

TerraformFoundation2 causes
Open runbook
Backend initialization required — run terraform initmedium

Backend initialization required: please run "terraform init"

TerraformFoundation2 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.