> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/rollback-provisioned-infra-with-the-terraform-rollback-step.md).

# Rollback Infrastructure with the Terraform Rollback step

This topic describes how to roll back your provisioned infrastructure and resources and return your environment to its pre-deployment state.

***

### What you will learn from this topic <a href="#what-you-will-learn-from-this-topic" id="what-you-will-learn-from-this-topic"></a>

* **Add Terraform Rollback steps:** Configure rollback steps in pipeline rollback sections to handle failed deployments.
* **Reference Provisioner Identifiers:** Link rollback steps to the infrastructure provisioned by Apply steps.
* **Understand rollback limitations:** Learn when rollback can and cannot be performed based on Terraform state.

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

Before using the Terraform Rollback step, ensure you have the following:

* **Terraform provisioning knowledge:** Familiarity with how Harness provisions infrastructure using Terraform. Go to [Terraform provisioning overview](/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/terraform-provisioning-with-harness.md) to understand the provisioning workflow.
* **Provisioner Identifier:** The same Provisioner Identifier used in your Terraform Apply step. Go to [Provision with the Terraform Apply step](/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/run-a-terraform-plan-with-the-terraform-apply-step.md) to learn how to set up provisioning.
* **Terraform installation:** Terraform must be installed on your delegates. Go to [Build custom delegate images with third-party tools](/harness-ai/use-harness-platform/delegates/delegate/install-delegates/build-custom-delegate-images-with-third-party-tools.md) to install Terraform on delegates.

***

### Terraform rollback <a href="#terraform-rollback" id="terraform-rollback"></a>

When rollback is performed, Harness rolls back the provisioned infrastructure to the previous successful version of the Terraform state using config files or the Terraform configuration from the latest successful deployment with a matching **Provisioner Identifier**. The Provisioner Identifier is a unique label that links Terraform Plan, Apply, and Rollback steps to the same configuration.

Harness will not increment the serial number in the Terraform state file but performs a hard rollback to the exact version of the state from the previous successful deployment.

Harness determines what to rollback using the **Provisioner Identifier**.

If you have made these settings expressions, Harness uses the values it obtains at runtime when it evaluates the expression.

#### Rollback limitations <a href="#rollback-limitations" id="rollback-limitations"></a>

Let us say you deployed two modules successfully already: module1 and module2. Next, you try to deploy module3, but deployment failed. Harness will roll back to the successful state of module1 and module2.

However, let us look at the situation where module3 succeeds and now you have module1, module2, and module3 deployed. If the next deployment fails, the rollback will only roll back to the Terraform state with module3 deployed. Module1 and module2 were not in the previous Terraform state, so the rollback excludes them.

Rollback is not possible if you run the Terraform Apply step with the **Skip state storage** option enabled and no Terraform backend is configured in your Terraform files. Using the Rollback step in such a scenario would be an incorrect setup and might cause an unexpected result.

***

### Add the Terraform Rollback step <a href="#add-the-terraform-rollback-step" id="add-the-terraform-rollback-step"></a>

You can add the Terraform Rollback step in the following rollback sections:

* Go to **Pipelines** > select a pipeline > select a stage > **Infrastructure** > **Dynamic Provisioning** > **Rollback** steps:

![](/files/xQB7Vs0Xfj0NhpeVDMP1)

* Go to **Pipelines** > select a pipeline > select a stage > **Execution** > **Rollback** steps:

![](/files/syHho7GF4u9L68vhBplV)

Add the **Terraform Rollback** step.

In **Name**, enter a name for the step. You can use the name to reference the Terraform Rollback settings.

***

### Reference the Provisioner Identifier <a href="#reference-the-provisioner-identifier" id="reference-the-provisioner-identifier"></a>

In **Provisioner Identifier**, enter the same Provisioner Identifier you used in the Terraform Plan and Apply steps.

![](/files/Xxp8VWIyBU7oGYX45bOv)

Click **Apply Changes**.

The Terraform Rollback step is added to the **Rollback** steps. When rollback succeeds, view execution logs in the pipeline execution details page to confirm the state was reverted.

***

### Command line options <a href="#command-line-options" id="command-line-options"></a>

{% hint style="info" %}
Currently, the command line options feature is behind the feature flag `CDS_TERRAFORM_CLI_OPTIONS_NG`. Contact [Harness Support](mailto:support@harness.io) to enable the feature.
{% endhint %}

This setting allows you to set the Terraform CLI options for Terraform commands depending on the Terraform step type. For example: `-lock=false`, `-lock-timeout=0s`.

![](/files/HwQcUShVnnhmNvSD5ipF)

***

### Skip Terraform refresh <a href="#skip-terraform-refresh" id="skip-terraform-refresh"></a>

Terraform refresh command will not run when this setting is selected.

***

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>Terraform rollback fails with state mismatch error in Harness CD pipeline</summary>

Verify the Provisioner Identifier matches the Apply step that created the infrastructure. Check that a previous successful Terraform state exists for the rollback to target.

</details>

<details>

<summary>Permission denied when rolling back infrastructure with Terraform Rollback step</summary>

Verify the connector used in the rollback step has permissions to modify the target resources. Check cloud provider IAM roles and policies.

</details>

<details>

<summary>Terraform rollback step cannot find previous successful state</summary>

Check that the Terraform Apply step completed successfully at least once before the rollback. Verify state storage is configured and accessible. Rollback requires a previous successful state to revert to.

</details>

<details>

<summary>Rollback step shows Provisioner Identifier mismatch</summary>

Ensure the Provisioner Identifier in the Rollback step exactly matches the identifier used in the Terraform Plan and Apply steps. Check for typos or case sensitivity issues.

</details>

***

### Next steps <a href="#next-steps" id="next-steps"></a>

You have configured a Terraform Rollback step to handle failed provisioning. The rollback step automatically reverts infrastructure to the previous successful state when deployments fail.

* Go to [Provision with the Terraform Apply step](/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/run-a-terraform-plan-with-the-terraform-apply-step.md) to understand the Apply workflow that rollback reverts.
* Go to [Remove infrastructure with the Terraform Destroy step](/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/remove-provisioned-infra-with-terraform-destroy.md) to permanently remove provisioned infrastructure.
* Go to [Terraform provisioning overview](/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/terraform-provisioning-with-harness.md) to understand rollback behavior and limitations.