An organization uses Terraform Cloud for remote state management. They have a workspace that uses the CLI-driven run workflow. A developer runs `terraform plan` locally and sees that the plan succeeds. However, when they push the same configuration to the version control system (VCS) connected to the workspace, the plan fails with a state lock error. What is the most likely reason?
Trap 1: The Terraform version in the VCS pipeline is different
A mismatch in Terraform versions between the local environment and the Terraform Cloud workspace or VCS pipeline typically results in errors related to provider compatibility, resource attribute parsing, or HCL syntax interpretation. These errors manifest as plan failures due to invalid configuration or state file schema issues, rather than an explicit state lock. A state lock specifically prevents concurrent operations on the state, which is distinct from configuration parsing problems.
Trap 2: The VCS branch is not configured as the workspace's working branch
If the VCS branch associated with a Terraform Cloud workspace does not match the configured working branch, Terraform Cloud would simply not trigger a run when changes are pushed to that non-matching branch. Alternatively, if a run is manually initiated or triggered by another mechanism, the workspace would operate on its *configured* branch, ignoring the unconfigured one. This scenario would lead to no run being initiated or the wrong code being executed, but it would not cause a state lock error, as the state locking mechanism is independent of branch configuration.
Trap 3: The VCS pipeline does not have access to the Terraform Cloud…
A lack of proper access permissions for the VCS pipeline to the Terraform Cloud workspace would manifest as authentication or authorization errors. Terraform Cloud would reject the API requests from the pipeline due to insufficient credentials or roles, preventing any operation, including state access. This would typically result in "permission denied" or "unauthorized" messages, rather than a state lock, which implies successful authentication but an inability to modify the state due to an existing lock.
- A
The Terraform version in the VCS pipeline is different
Why wrong: A mismatch in Terraform versions between the local environment and the Terraform Cloud workspace or VCS pipeline typically results in errors related to provider compatibility, resource attribute parsing, or HCL syntax interpretation. These errors manifest as plan failures due to invalid configuration or state file schema issues, rather than an explicit state lock. A state lock specifically prevents concurrent operations on the state, which is distinct from configuration parsing problems.
- B
The local `terraform plan` left the state locked in Terraform Cloud
When a `terraform plan` is executed locally against a Terraform Cloud remote backend, it acquires a state lock to prevent concurrent modifications. If the local process terminates unexpectedly (e.g., due to a crash, network interruption, or manual cancellation) before the lock can be explicitly released, the state remains locked. This persistent lock then prevents any subsequent `terraform plan` or `terraform apply` operations, whether local or initiated via a VCS pipeline, from proceeding, leading to a "state locked" error.
- C
The VCS branch is not configured as the workspace's working branch
Why wrong: If the VCS branch associated with a Terraform Cloud workspace does not match the configured working branch, Terraform Cloud would simply not trigger a run when changes are pushed to that non-matching branch. Alternatively, if a run is manually initiated or triggered by another mechanism, the workspace would operate on its *configured* branch, ignoring the unconfigured one. This scenario would lead to no run being initiated or the wrong code being executed, but it would not cause a state lock error, as the state locking mechanism is independent of branch configuration.
- D
The VCS pipeline does not have access to the Terraform Cloud workspace
Why wrong: A lack of proper access permissions for the VCS pipeline to the Terraform Cloud workspace would manifest as authentication or authorization errors. Terraform Cloud would reject the API requests from the pipeline due to insufficient credentials or roles, preventing any operation, including state access. This would typically result in "permission denied" or "unauthorized" messages, rather than a state lock, which implies successful authentication but an inability to modify the state due to an existing lock.