Additionally, unlocking the state in Kubernetes failed…

Error message

%v
				Additionally, unlocking the state in Kubernetes failed:

				Error message: %q
				Lock ID (gen): %v
				Secret Name: %v

				You may have to force-unlock this state in order to use it again.
				The Kubernetes backend acquires a lock during initialization to ensure
				the initial state file is created.

What it means

Compound error during k8s backend StateMgr init: the backend creates the initial empty state and if WriteState or PersistState fails, it attempts to release the lock via the unlock closure (backend_state.go:119-145). If unlocking ALSO fails, this multi-line message wraps the base error together with the unlock error, the generated lock ID, and the Secret name. It tells the operator the state is now locked and must be force-unlocked.

Solutions

Read the error for the generated Lock ID and Secret Name, then run 'terraform force-unlock <Lock ID>'.
Fix the RBAC so the service account can create Secrets and update Leases in the namespace.
Check etcd/API server health if writes are failing cluster-wide.
After force-unlock, re-run terraform init.

Defensive patterns

Strategy: try-catch

Try / catch

// Parse the compound error to extract the Lock ID for force-unlock:
// _, diags := b.StateMgr(name)
// for _, d := range diags {
//   msg := d.Description().Summary
//   if strings.Contains(msg, "unlocking the state in Kubernetes failed") {
//     lockID := extractLockID(msg) // regex 'Lock ID \(gen\): ([^\s]+)')
//     runTerraformForceUnlock(lockID)
//   }
// }

Prevention

Grant the backend service account RBAC to create Secrets and update Leases before first init.
Verify etcd/API server health before initializing the backend.
Keep the generated lock ID accessible until init succeeds so force-unlock is possible.

When it happens

Trigger: WriteState fails (e.g., Secret write RBAC denied, etcd unavailable) AND the subsequent Unlock fails (e.g., lease update conflict, permissions). The state ends up locked with the generated lockID that the operator does not know.

Common situations: Insufficient RBAC for both Secret create and Lease update during initial provisioning; etcd/quorum issues during init; a race where the lease was modified between lock and unlock.

Related errors

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/2c59f4ec3e6841d5. Report an issue: GitHub.

Appendix: source

Thrown at internal/backend/remote-state/kubernetes/backend_state.go:128

		secretName, err := c.createSecretName(0)
		if err != nil {
			return nil, diags.Append(err)
		}

		// Local helper function so we can call it multiple places
		unlock := func(baseErr error) error {
			if err := stateMgr.Unlock(lockID); err != nil {
				const unlockErrMsg = `%v
				Additionally, unlocking the state in Kubernetes failed:

				Error message: %q
				Lock ID (gen): %v
				Secret Name: %v

				You may have to force-unlock this state in order to use it again.
				The Kubernetes backend acquires a lock during initialization to ensure
				the initial state file is created.`
				return fmt.Errorf(unlockErrMsg, baseErr, err.Error(), lockID, secretName)
			}

			return baseErr
		}

		if err := stateMgr.WriteState(states.NewState()); err != nil {
			unlockErr := unlock(err)
			return nil, diags.Append(unlockErr)
		}
		if err := stateMgr.PersistState(nil); err != nil {
			unlockErr := unlock(err)
			return nil, diags.Append(unlockErr)
		}

		// Unlock, the state should now be initialized
		if err := unlock(nil); err != nil {
			return nil, diags.Append(err)
		}

View on GitHub (pinned to d32a084675)