Terraform State Lock Conflict Retry Prompt Template

This prompt is for infrastructure engineers and SRE teams who need an AI-assisted decision when a Terraform plan or apply fails with a state lock error. Instead of manually inspecting lock metadata and guessing whether to retry or force-unlock, this prompt produces a structured, safety-checked decision. Use it inside CI/CD pipelines, operator chatbots, or runbook automation where a lock conflict requires fast, auditable resolution. The prompt assumes you already have the raw error output and lock metadata available. It does not replace Terraform's native locking mechanism or your team's change management policy.

The ideal user has access to the full Terraform error output, the lock ID, lock creation timestamp, lock holder identity (user, CI runner, or machine identity), and the operation that triggered the conflict. The prompt requires these inputs to assess collision risk: Is the lock holder still active? Is the conflicting operation a plan (read-only) or an apply (mutating)? Has the lock exceeded a reasonable timeout threshold? Without this context, the model cannot distinguish between a stale lock that is safe to force-unlock and an active operation that must be allowed to complete. The prompt also requires a risk tolerance parameter—low for production state files, higher for ephemeral development environments—to calibrate the decision threshold.

Do not use this prompt when the lock holder is unknown, when the state backend is corrupted, or when multiple team members are actively applying changes to the same workspace. In those scenarios, automated decisions risk state file corruption or split-brain conditions. The prompt is also inappropriate for state files stored in backends without locking support, where the error may indicate a different class of problem. Always pair this prompt with a human-approval gate for production state files, and ensure your harness logs the full decision rationale for post-incident review. The next section provides the copy-ready prompt template you can adapt to your specific Terraform backend and operational policies.

This prompt template is designed to be pasted directly into your AI harness when a Terraform operation fails due to a state lock conflict. It instructs the model to act as an infrastructure reliability engineer, analyzing the provided error context, lock metadata, and operation details to produce a safe, structured decision. The output is a strict JSON schema suitable for programmatic consumption by a retry orchestrator or a human approval queue. Replace every square-bracket placeholder with real data from your CI/CD pipeline or operator console before sending the request.

textCopy
You are an infrastructure reliability engineer diagnosing a Terraform state lock conflict.
Your task is to analyze the provided error context and produce a structured decision.

# INPUT
- Error Output: [TERRAFORM_ERROR_OUTPUT]
- Lock ID: [LOCK_ID]
- Lock Holder Information: [LOCK_HOLDER_INFO]
- Current Operation: [CURRENT_OPERATION]
- Operation Timestamp: [OPERATION_TIMESTAMP]
- State File Path: [STATE_FILE_PATH]
- Recent State Changes: [RECENT_STATE_CHANGES]

# CONSTRAINTS
- Do not recommend `terraform force-unlock` unless the lock holder is confirmed dead, the operation has timed out beyond a safe threshold, and no conflicting writes are in progress.
- If the lock holder is active, recommend a retry with exponential backoff.
- Always verify state integrity before suggesting a force-unlock.
- If the state file shows signs of corruption or a partial write, escalate for manual recovery.

# OUTPUT_SCHEMA
Return a single JSON object with the following fields:
{
  "decision": "retry" | "force_unlock" | "escalate",
  "confidence": "high" | "medium" | "low",
  "reasoning": "A concise explanation of the decision.",
  "lock_holder_status": "active" | "dead" | "unknown",
  "collision_detected": true | false,
  "state_integrity_check": "clean" | "suspicious" | "corrupted",
  "recommended_action": "A specific next step, including backoff timing or escalation contact.",
  "risk_summary": "A brief description of the primary risk if the recommended action is taken."
}

To adapt this template, ensure the [TERRAFORM_ERROR_OUTPUT] includes the full, raw error message, as the model uses specific keywords like 'lock', 'timeout', and 'ID' to parse the situation. The [LOCK_HOLDER_INFO] should be populated by querying your backend (e.g., DynamoDB, GCS, or a Terraform Cloud API call) to determine if the holder process is still alive. If you cannot determine the holder's status, set the value to 'unknown' and the model will default to a safer retry posture. After receiving the JSON output, your application harness must validate the schema before acting on the decision field, especially for destructive force_unlock actions which should always require explicit human approval in a production environment.

This prompt is designed to be invoked by an automation harness—typically a CI/CD pipeline, a runbook automation tool, or an operator CLI—immediately after a terraform apply or terraform plan command exits with a state lock acquisition error. The harness must capture the full stderr output, the current Terraform workspace, the lock ID if present, and any available lock metadata from terraform force-unlock -force-unlock <LOCK_ID> dry-run output. Do not call this prompt in isolation without the raw error context; the model needs the exact lock error message, the operation that was attempted, and the lock holder information to make a safe retry-or-force-unlock decision.

The implementation should follow a strict pre- and post-processing contract. Before calling the model, validate that the captured error output contains a recognizable state lock conflict string (e.g., Error acquiring the state lock, state blob is already locked). If the error does not match, route to a generic infrastructure error handler instead. After receiving the model's response, parse the structured decision object and enforce a hard gate: if the decision is force_unlock, the harness must require an explicit human approval step (e.g., a Slack notification with a reaction-based confirmation or a CI pipeline manual approval job) before executing terraform force-unlock. Log the full prompt, response, lock ID, and the human approver's identity to an audit trail. For retry decisions, implement the recommended backoff using an exponential backoff with jitter library, respecting a maximum retry budget of 3 attempts before escalating to a human operator.

Model choice matters here. Use a model with strong instruction-following and structured output capabilities (e.g., Claude 3.5 Sonnet, GPT-4o) and set temperature=0 to maximize deterministic decision-making. The prompt's output schema should be enforced via the model's JSON mode or a structured output API to prevent parsing failures. Implement a post-response validator that checks for the presence of required fields (decision, lock_id, reasoning, safety_checks_passed) and rejects malformed responses, triggering a single retry with a simplified fallback prompt that asks only for a binary retry or escalate decision. Never automatically execute a force_unlock based solely on the model's output; the cost of corrupting Terraform state far outweighs the latency of human review.