How to Use Terraform State Push: Syntax and Examples

Use terraform state push to manually upload a local Terraform state file to the configured backend. The command syntax is terraform state push [options] PATH, where PATH is the state file to upload. This is useful when you need to replace or restore the state in your backend.

Syntax

The basic syntax of terraform state push is:

• terraform state push [options] PATH

Where:

• PATH is the path to the local Terraform state file you want to upload.
• --force option allows overwriting the existing state in the backend without confirmation.

bash

terraform state push [options] PATH

Example

This example shows how to push a local state file named terraform.tfstate to the configured backend.

bash

terraform state push terraform.tfstate

Output

Success! State was pushed to the backend.

Common Pitfalls

Common mistakes when using terraform state push include:

• Forgetting to use the --force flag when overwriting an existing state, which causes the command to fail.
• Uploading a corrupted or incomplete state file, which can break your Terraform environment.
• Using terraform state push without understanding that it replaces the entire state, potentially causing resource mismatches.

Always backup your current state before pushing a new one.

bash

## Wrong way (without --force, overwriting existing state)
terraform state push terraform.tfstate

## Right way (force overwrite)
terraform state push --force terraform.tfstate

Quick Reference

Option	Description
PATH	Local path to the Terraform state file to upload
--force	Overwrite existing state in backend without confirmation

Key Takeaways

Use terraform state push to manually upload a local state file to the backend.

Include --force to overwrite existing state without prompt.

Always backup your current state before pushing a new one.

Uploading a corrupted state file can break your Terraform setup.

terraform state push replaces the entire state in the backend.