Terraform Apply Error Recovery Prompt

This prompt is designed for infrastructure engineers and platform teams who are blocked by a failed terraform plan or terraform apply and need to move past the error quickly. The ideal user is someone who can read a Terraform configuration and an error message but needs assistance reasoning about the underlying provider API contract, state file integrity, or resource dependency graph that caused the failure. The job-to-be-done is not just to get a corrected block of HCL, but to receive a root-cause explanation that builds the engineer's mental model of the failure, enabling them to prevent similar issues in the future. You should use this prompt when the error is non-trivial—meaning it is not a simple typo, a missing variable, or a copy-paste mistake that a linter would catch.

The prompt requires two concrete inputs to be effective: the exact Terraform configuration block that is failing, and the complete, unredacted error output from the terraform CLI. Without both, the model lacks the context to distinguish between a provider version mismatch, a state lock contention, a misconfigured remote backend, or an API-level validation error from the cloud provider. The prompt instructs the model to act as a senior infrastructure engineer, which means it should prioritize fixes that are idempotent, respect existing resource dependencies, and do not introduce destructive changes like forced re-creation unless explicitly justified. The harness that wraps this prompt should immediately pipe the corrected configuration into terraform validate and a targeted terraform plan to confirm the fix is syntactically valid and produces a non-destructive diff.

Do not use this prompt for initial architecture design, for generating new Terraform modules from scratch, or for errors caused by external network partitions that no configuration change can resolve. It is also inappropriate for failures where the root cause is a manual state manipulation (terraform state rm/import) that has left the state file inconsistent in a way that requires a human operator to decide on a reconciliation strategy. In those cases, the prompt may produce a plausible-looking fix that masks the underlying state corruption. The next step after reading this section is to gather your failing configuration and error output, then proceed to the prompt template to begin the recovery loop.

The following prompt template is designed to be pasted directly into your AI harness. It instructs the model to act as a senior infrastructure engineer, consuming a failed Terraform configuration and its error output to produce a corrected configuration and a clear diagnosis. The template uses square-bracket placeholders for all dynamic inputs, ensuring you can swap in the specific error, configuration, and constraints for your incident. Before using this in a production pipeline, you must replace every placeholder with the actual values from your failed run. The prompt is self-contained: it includes the required role, the input schema, the expected output structure, and explicit constraints that prevent the model from introducing new resources or making unauthorized changes.

textCopy
You are a senior infrastructure engineer specializing in Terraform and cloud provider APIs. Your task is to diagnose a failed `terraform apply` or `terraform plan` operation and produce a corrected version of the configuration.

## INPUT
You will receive the following:
- **Original Configuration**: The Terraform HCL that was applied.
  ```hcl
  [FAILED_TERRAFORM_CONFIGURATION]

• Error Output: The full error message from the Terraform CLI.

  textCopy
  [TERRAFORM_ERROR_OUTPUT]

• Provider Context: The provider and version in use.

  textCopy
  [PROVIDER_NAME_AND_VERSION]

• State Context (optional): A summary of the relevant existing state, if the error involves a state mismatch.

  textCopy
  [RELEVANT_STATE_SUMMARY]

TASK

1. Diagnose the root cause: Identify whether the error is a syntax issue, a provider API constraint violation, a state mismatch, a dependency ordering problem, or a resource naming conflict.
2. Produce a corrected configuration: Output the full, corrected HCL for the affected resources. Do not omit any original resource blocks unless they are the direct cause of the error and must be removed.
3. Explain the fix: Provide a concise, step-by-step explanation of what was changed and why, referencing the specific error message.

CONSTRAINTS

• Do not add new resources, data sources, or providers that were not in the original configuration.
• Do not change resource names or identifiers unless the error is a naming conflict that requires it.
• Preserve all existing comments and formatting where possible.
• If the error is a state mismatch, do not suggest terraform import or state manipulation commands unless explicitly allowed by [ALLOW_STATE_COMMANDS].
• If the error is a provider bug or an API limitation, suggest a practical workaround and flag it with # WORKAROUND: [reason].
• If you cannot determine a safe fix with the provided information, respond with a structured uncertainty report instead of guessing.

OUTPUT FORMAT

Respond in JSON with the following structure:

jsonCopy
{
  "diagnosis": {
    "error_category": "syntax_error | provider_constraint | state_mismatch | dependency_error | naming_conflict | unknown",
    "root_cause": "A concise description of the root cause, referencing the error message.",
    "affected_resources": ["list", "of", "resource", "addresses"]
  },
  "corrected_configuration": "The full corrected HCL as a single string.",
  "explanation": [
    "Step 1: What was changed and why.",
    "Step 2: ..."
  ],
  "uncertainty_report": null  // Or an object with "reason" and "suggested_next_steps" if the fix is uncertain.
}

RISK LEVEL

[RISK_LEVEL: low | medium | high]

• If RISK_LEVEL is "high", include a # REVIEW REQUIRED comment on every changed line and add a human_review_notes field to the output JSON explaining what an engineer must verify before applying.

To adapt this template for your environment, start by replacing the core placeholders: [FAILED_TERRAFORM_CONFIGURATION] and [TERRAFORM_ERROR_OUTPUT] must come directly from your CI/CD logs or local terminal. The [PROVIDER_NAME_AND_VERSION] placeholder should be populated from your required_providers block or the .terraform.lock.hcl file. The [RELEVANT_STATE_SUMMARY] is optional but critical for state-mismatch errors; you can generate it by running terraform state list and terraform state show on the affected resources. The [ALLOW_STATE_COMMANDS] boolean should be set to true only if your harness is permitted to suggest terraform state rm or terraform import commands; in most production pipelines, this should be false to prevent unsafe state manipulation. The [RISK_LEVEL] placeholder should be set dynamically based on the blast radius of the affected resources—for example, changes to network ACLs, IAM policies, or database instances should be marked as high.

When wiring this prompt into an application, ensure the harness validates the model's output before applying any changes. The corrected configuration must pass terraform validate and a targeted terraform plan against the original state. If the plan shows unexpected resource destruction or recreation, the harness should block the change and escalate for human review. For high-risk changes, the harness should automatically append a # REVIEW REQUIRED comment to every modified line and create a pull request rather than applying directly. Never allow an AI-generated fix to be applied to production infrastructure without a human approval gate when RISK_LEVEL is high.

The Terraform Apply Error Recovery Prompt is designed to sit inside a remediation step that triggers only after terraform apply or terraform plan returns a non-zero exit code. The harness captures the full error output, the original Terraform configuration files, and any relevant state or provider context before invoking the model. This prompt is not a replacement for terraform validate or terraform fmt; it is a recovery tool for semantic and provider-level errors that static checks cannot catch, such as resource conflicts, missing dependencies, or API-side validation failures.

Wire the prompt into a pipeline stage that runs after a failed apply. The input assembly step must collect: the exact error message from stderr, the content of the offending .tf files, the Terraform and provider versions, and the target workspace or environment name. After the model returns a corrected configuration, the harness must run terraform validate on the proposed fix. If validation passes, execute terraform plan in a non-destructive mode (e.g., with -target scoped to the affected resource) and diff the plan against the expected state. Only if the plan is clean and contains no unexpected deletions should the fix proceed to a manual approval gate or an automated apply in non-production environments. Log every recovery attempt, including the original error, the model's suggested fix, the validation result, and the plan diff, for audit and regression testing.

Set a strict retry budget: no more than two recovery attempts per failed apply. If the first fix fails validation or produces a plan with destructive changes, feed the new error back to the model with the updated context and allow one more attempt. After two failures, escalate to a human operator and attach the full log trail. For production environments, always require a human to approve the plan before applying the corrected configuration. Avoid running this recovery loop against stateful resources like databases or persistent volumes without a snapshot or backup step preceding the retry. The most common failure mode is the model suggesting a resource recreation when an in-place update or state import would suffice; the plan diff review catches this before it reaches production.