Terramate stack hierarchy limits on circular dependency detection

Circular Dependency Detection in Terramate

The terramate generate command does not perform a standalone, deterministic validation of the entire dependency graph specifically to block file generation. Instead, Terramate focuses on the generation of configuration files based on templates. Circular dependencies typically manifest during the graph resolution phase—specifically when the orchestrator attempts to resolve variable interpolations or determine the deployment order for operations like terramate run terraform plan.

Likely Behavior and Constraints

While Terramate manages the hierarchy through terramate.tm.hcl files, the following behaviors are observed in large-scale architectures:

• Resolution Errors: If a circular dependency is introduced in the stack definitions, the orchestrator will generally encounter a resolution error when it attempts to traverse the dependency tree. This prevents the execution of the underlying Terraform commands but may not always stop the initial file generation if the cycle exists only in the logic of the dependency graph and not in the template interpolation.
• Interpolation Loops: A critical risk occurs when variables are cross-referenced across stacks in a loop. This can lead to infinite recursion during the interpolation phase, which typically results in a stack overflow or a timeout error from the CLI.
• Nesting Depth: There is no hard-coded architectural limit on nesting depth; however, performance degrades as the complexity of the Directed Acyclic Graph (DAG) increases. Deeply nested hierarchies increase the computational overhead for every generate or run command, as the tool must evaluate the inheritance chain for every stack.

Verification Steps

To verify how your specific version of Terramate handles cycles, you can perform a scoped test:

1. Create two stack directories: stack-a and stack-b.
2. In stack-a/terramate.tm.hcl, define a dependency on stack-b.
3. In stack-b/terramate.tm.hcl, define a dependency on stack-a.
4. Run terramate generate and then attempt a deployment command (e.g., terramate run terraform plan) to observe where the cycle is intercepted.

Diagnostic Detail Needed: Are you experiencing these issues during the generate phase (template rendering) or during the run phase (orchestration of Terraform)? The resolution path differs depending on whether the cycle is in the file structure or the execution graph.