OpenTofu state encryption configuration errors in CI

By Daniel Zoghalchali·Latchkey

State encryption is an OpenTofu feature with no Terraform equivalent. It encrypts state and plan files at rest using a configured key provider. This error means the encryption block is invalid or the key needed to decrypt existing state is unavailable in CI.

What this error means

tofu init, plan, or apply fails with an encryption error such as "decryption failed for state" or "no matching key provider found", usually because the key env var or PBKDF2 passphrase is not set on the runner.

Error: Encryption configuration failed

decryption failed: no key provider named "pbkdf2.mykey" could produce a key;
the passphrase environment variable is empty.

Common causes

The decryption key is not present in CI

The encryption block references a key provider whose secret (a passphrase or KMS key) was not injected into the job, so tofu cannot decrypt existing state.

A malformed encryption or key_provider block

The encryption block names a method or key provider incorrectly, or omits a required attribute, so tofu rejects the configuration.

How to fix it

Inject the encryption key as a secret

1. Store the passphrase or key material as a CI secret.
2. Expose it under the exact env var the key provider expects.
3. Re-run tofu so it can decrypt and re-encrypt state.

env:
  TF_VAR_encryption_passphrase: ${{ secrets.TOFU_ENCRYPTION_PASSPHRASE }}

Declare a valid encryption block

Define a key provider and a method, then apply it to state and plan. Keep the passphrase out of the file.

terraform {
  encryption {
    key_provider "pbkdf2" "mykey" {
      passphrase = var.encryption_passphrase
    }
    method "aes_gcm" "secure" {
      keys = key_provider.pbkdf2.mykey
    }
    state { method = method.aes_gcm.secure }
  }
}

How to prevent it

• Keep encryption key material in CI secrets, never in the config.
• Set the key env var in every job that reads or writes state.
• Roll keys with a fallback method so old state still decrypts.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation