🚨 OpenTofu Error: 'decryption failed' — Cause, Fix, and Troubleshooting Guide

Overview

OpenTofu has native state and plan encryption — a feature distinct from Terraform. When enabled, state is encrypted at rest using a key provider (PBKDF2 passphrase, AWS KMS, GCP KMS, or OpenBao/Vault). If the key OpenTofu has cannot decrypt the stored state — wrong passphrase, rotated key, or missing key provider — it fails before it can read anything:

Error: decryption failed

  Failed to decrypt the state file using method "aes_gcm" with key provider
  "pbkdf2.mykey": cipher: message authentication failed.

  This may indicate the encryption key or passphrase has changed, or the state
  was encrypted with a different key provider than the one currently configured.

Symptoms

• Any tofu command fails with decryption failed / cipher: message authentication failed.
• The state (or plan) file is encrypted but the current key cannot open it.
• Happens after rotating a passphrase/KMS key without a fallback, or on a runner missing the key.
• CI fails while local works (the passphrase/KMS access differs).

Common Root Causes

• Wrong passphrase — TF_VAR/env passphrase differs from the one that encrypted the state.
• Rotated key without fallback — the old key was removed before re-encrypting.
• Missing key provider access — no permission on the KMS/Vault key on this runner.
• Config mismatch — encryption method/key_provider changed and no longer matches the ciphertext.
• Env var not set — the passphrase/key isn’t present in the environment at all.

How to diagnose

Confirm the encryption config and which key provider is active:

grep -nA12 'encryption' *.tf

Check the passphrase/key material is present in this environment:

env | grep -iE 'PASSPHRASE|KMS|VAULT' | sed 's/=.*/=***/'

Verify KMS/Vault access if you use those key providers:

aws kms describe-key --key-id alias/tofu-state >/dev/null && echo kms-ok

Fixes

Provide the correct passphrase/key the state was encrypted with:

export TF_VAR_state_passphrase='the-original-passphrase'
tofu plan

Use a fallback key to decrypt during rotation, so OpenTofu can read old ciphertext with the previous key while writing with the new one:

terraform {
  encryption {
    key_provider "pbkdf2" "new" { passphrase = var.new_passphrase }
    key_provider "pbkdf2" "old" { passphrase = var.old_passphrase }
    method "aes_gcm" "new" { keys = key_provider.pbkdf2.new }
    method "aes_gcm" "old" { keys = key_provider.pbkdf2.old }
    state {
      method   = method.aes_gcm.new
      fallback { method = method.aes_gcm.old }
    }
  }
}

Then re-apply to re-encrypt state with the new key, and remove the fallback once complete:

tofu apply   # reads with fallback, writes with new key

Grant KMS/Vault access on the runner if that is the key provider.

What to watch out for

• Always rotate keys with a fallback block, never by swapping the key outright — otherwise existing state becomes unreadable.
• The passphrase/key must be present in every environment that runs tofu, including CI.
• Keep the old key available until every state and plan file has been re-encrypted.
• State encryption is OpenTofu-specific; Terraform state has no equivalent, so migrated pipelines must supply the key.

Related

• OpenTofu Error: ‘Invalid encryption configuration’ — Cause, Fix, and Troubleshooting Guide
• OpenTofu Error: ‘Error loading state: AccessDenied’ — Cause, Fix, and Troubleshooting Guide
• Rotating OpenTofu State Encryption Keys