Terraform Errors

This article covers errors specific to the Terraform layer that underlies Cloud Manager — template authoring errors, provider plugin issues, state conflicts, destroy failures, and variable injection problems. For higher-level issues (quota, credentials, network), see Provisioning Failures and Connectivity Issues.

Terraform errors are most relevant to custom Terraform models, but some can affect built-in blueprint models as well (blueprints are themselves Terraform templates running under the hood).

Reading a Terraform Error

Terraform errors follow a consistent structure. When you see one in the deployment log, look for:

• The resource block it occurred in (e.g., aws_instance.vdi_instance)
• The specific error message from Terraform or the provider plugin
• The line number in the template (for syntax errors)

For provider-side errors, the message often includes the provider’s own error code and explanation (for example, AWS InsufficientInstanceCapacity). Use that provider-specific message to drill further into the provider’s documentation.

Provider Plugin Download Failed

Symptom: the deployment log shows an error early in the run mentioning failed to download provider plugin or could not connect to registry.terraform.io.

Terraform requires outbound HTTPS access from the broker host to registry.terraform.io and releases.hashicorp.com to download provider plugins. If the broker is behind a proxy or in an air-gapped environment, the network configuration for these endpoints is handled at the Workspace level — see Thinfinity® Workspace Best Practices for Production Environments for outbound connectivity and proxy guidance.

Authentication / Provider Credentials

Symptom: the log shows a provider-specific authentication error (e.g., InvalidAccessKeyId, AuthenticationFailed, 401 Unauthorized).

Cause: the credentials passed to the Terraform provider are invalid or lack the required permissions.

Resolution:

1. Open the credential set in the Credentials tab (see Credentials) and confirm the values are current. Cloud Manager validates credentials when they are added or edited; if they were valid then but failing now, they may have been rotated or revoked at the provider.
2. If the credential set was added successfully but Terraform still fails with an authentication error, the credentials may have read/list access but lack the write permissions Terraform needs for provisioning. Review the provider’s credential page in Credentials for the exact permissions required.
3. Rotate the credentials at the provider, update them in Cloud Manager, and retry.

State Lock Conflict

Symptom: the deployment log mentions “state locked” or “could not acquire state lock”.

Cloud Manager runs Terraform with state locking disabled and keeps a separate local state for each deployment, so this error does not occur during normal Cloud Manager operation. If you see it, a Terraform operation was run manually against the broker’s working directory — for example, while inspecting or repairing a deployment by hand.

Resolution:

1. Confirm that no manual Terraform operation is running against that deployment’s working directory on the broker host.
2. Cloud Manager has no in-product unlock action. Clear the stale lock on the broker host — for example, run terraform force-unlock in that deployment’s directory — then retry the operation from Cloud Manager.

Missing Required Variables

Symptom: the log shows an error like No value for required variable "instance_type" or Missing required argument.

Cause: the template declares a variable that was not supplied by Cloud Manager. This happens when:

• A variable is declared in variables.tf without a default and is not in schema.json — the wizard doesn’t know to ask for it, so it goes unset.
• The variable name in schema.json doesn’t match the name in variables.tf — the wizard collects input for one name; Terraform expects another.

Resolution:

1. Verify every required variable in variables.tf is either:
   • Declared with a default value, OR
   • Exposed in schema.json for user input, OR
   • A reserved variable that Cloud Manager populates (vdi_instances, vmname)
2. Verify the variable names match exactly between variables.tf, schema.json, and the resource references in main.tf.
3. See schema.json and uischema.json Reference.

Resource Label Mismatch

Symptom: the deployment succeeds on the provider side, but Cloud Manager cannot find or manage the provisioned VM afterward.

Cause: the VM resource in the template does not use the required label vdi_instance. Cloud Manager identifies the manageable resource by this label — without it, the VM exists at the provider but is invisible to Cloud Manager.

Resolution:

1. Open the template’s main.tf.

2. Locate the VM resource block.

3. Ensure it is labeled vdi_instance:

   resource "aws_instance" "vdi_instance" {
     # ...
   }
   

4. Update the model with the corrected template and redeploy.

See Terraform Overview — VM Template.

Multiple Instantiation Not Working

Symptom: the template runs but provisions only one VM, regardless of the model’s instance count configuration.

Cause: the template is not iterating over the vdi_instances list.

Resolution:

1. Ensure the VM resource uses for_each = toset(var.vdi_instances):

   resource "aws_instance" "vdi_instance" {
     for_each      = toset(var.vdi_instances)
     ami           = var.ami
     instance_type = var.instance_type
     tags = {
       Name = each.value
     }
   }
   

2. Ensure the variable vdi_instances is declared in variables.tf as a list(string).

3. Ensure vdi_instances is not in schema.json — it is a reserved variable populated by Cloud Manager.

See Terraform Overview — Multiple Instantiation.

Shared Template Output Not Consumed

Symptom: the deployment fails with errors about missing resources that should have been created by the Shared Template.

Cause: the VM Template is not correctly consuming the outputs from the Shared Template.

Resolution:

1. Confirm the Shared Template declares outputs for all shared resources:

   output "subnet_id" {
     value = azurerm_subnet.my_terraform_subnet.id
   }
   

2. Confirm the VM Template declares matching input variables and uses var.<name> to reference them:

   ip_configuration {
     subnet_id = var.subnet_id
   }
   

3. See Terraform Overview — Shared Template.

Destroy Operation Fails

Symptom: a Destroy operation (manual or triggered by the model’s Destroy Settings) fails or leaves resources behind.

Common causes are listed below.

If a destroy leaves resources behind at the provider, clean them up manually in the provider console to prevent ongoing costs.

State Drift

Symptom: Cloud Manager shows an instance as Active that no longer exists at the provider, or as destroyed when it still exists.

Cause: the Terraform state and the actual provider resources have diverged, usually because:

• A resource was modified or deleted outside of Cloud Manager (directly in the provider console, via provider CLI)
• A Terraform operation crashed mid-way
• State storage corruption

Resolution:

1. Use Refresh on the affected instance. Cloud Manager queries the provider directly and updates the instance’s recorded status. This resolves drift that is limited to the status Cloud Manager shows.
2. If the underlying resources have actually diverged — not just the displayed status — destroy the affected deployment and reprovision. Cloud Manager does not expose a standalone terraform refresh or reconcile action.

Template Validation Failed

Symptom: the deployment fails immediately with an HCL syntax error or validation error.

Resolution:

1. Validate the template locally with terraform fmt and terraform validate before importing.
2. Review the specific line number and error from the deployment log.
3. Common issues: missing commas in maps, mismatched braces, invalid resource references, incorrect variable types.

See Also

• Troubleshooting
• Custom Terraform Templates
• Terraform Overview
• Create a Model Using a Custom Terraform Template
• schema.json and uischema.json Reference
• Connectivity Issues
• Provisioning Failures