Terraform: per-environment backends with partial backend config

TL;DR

Use env vars or partial config with the secret bits omitted. Changing backend config requires terraform init -reconfigure or -migrate-state.

Steps

1. Never put credentials in backend config files that get committed. Use env vars or partial config with the secret bits omitted.
2. Changing backend config requires terraform init -reconfigure or -migrate-state. Plain terraform init will refuse or silently keep the old backend.
3. One backend block, many -backend-config files. If you see two backend blocks for two envs, that is the fork to delete.
4. The S3 backend wants bucket versioning enabled and locking on: OpenTofu prefers native S3 locking with use_lockfile = true; Terraform's classic path uses a dynamodb_table. Verify which your toolchain supports before choosing.

When to use

You are seeing this: Agents often copy the whole config per environment and hardcode a different backend block in each copy. Use this skill when you run into "Terraform: per-environment backends with partial backend config".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

Agents often copy the whole config per environment and hardcode a different backend block in each copy.

Backend configuration can be partial with remaining settings supplied via -backend-config at init; changing backend config needs -reconfigure or -migrate-state. S3 backend: uselockfile=true enables native S3 locking via conditional writes; DynamoDB locking uses dynamodbtable; bucket versioning is highly recommended. Verified against live docs 2026-09-26.