Error Acquiring State Lock when Migrating State to Terraform Cloud/Enterprise

Problem

When you migrate state from an existing backend to HCP Terraform or Terraform Enterprise, the operation fails with a resource not found error while attempting to acquire a state lock.

Example with remote backend

$ terraform init -migrate-state

Initializing the backend...
Terraform detected that the backend type changed from "azurerm" to "remote".

╷
│ Error: Error acquiring the state lock
│ 
│ Error message: resource not found
│ 
│ Terraform acquires a state lock to protect the state from being written
│ by multiple users at the same time.
│ Please resolve the issue above and try
│ again. For most commands,
│ you can disable locking with the "-lock=false"
│ flag, but this is not recommended.
╵

Example with cloud block (Terraform v1.1+)

$ terraform init

Initializing Terraform Cloud...
Migrating from backend "azurerm" to Terraform Cloud.

Do you wish to proceed?
  As part of migrating to Terraform Cloud, Terraform can optionally copy your
  current workspace state to the configured Terraform Cloud workspace.

  Answer "yes" to copy the latest state snapshot to the configured
  Terraform Cloud workspace.

  Answer "no" to ignore the existing state and just activate the configured
  Terraform Cloud workspace with its existing state, if any.

  Should Terraform migrate your existing state?
  Enter a value: yes

╷
│ Error: Error acquiring the state lock
│ 
│ Error message: resource not found
│ 
│ Terraform acquires a state lock to protect the state from being written
│ by multiple users at the same time.
│ Please resolve the issue above and try
│ again. For most commands,
│ you can disable locking with the "-lock=false"
│ flag, but this is not recommended.
╵

Cause

This error occurs when the authenticated HCP Terraform or Terraform Enterprise user does not have sufficient permissions to lock workspaces. The target workspace must be locked while state is being uploaded.

Although the error might seem related to the existing backend, enabling trace logging can confirm that the lock on the source state was acquired successfully. The following example shows a successful Lease Blob request to an azurerm backend, indicating the issue is with the target workspace in HCP Terraform or Terraform Enterprise.

$ TF_LOG=trace terraform init
## ...
2023-05-16T09:59:28.191-0400 [DEBUG] Azure Backend Response for https://tfstatet5y9z.blob.core.windows.net/tfstate/prod.terraform.tfstate?comp=lease: HTTP/1.1 201 Created
## ...

Solution

To resolve this issue, you must use credentials for a user or team that has permission to lock workspaces in the target HCP Terraform or Terraform Enterprise organization.

Locking a workspace requires membership in a team with at least one of the following permissions:

• Membership in the owners team.
• A team with "Manage all workspaces" and/or “Manage all projects” organization permissions.
• A team with “Project Admin” project permissions.

Take one of the following actions to proceed with the migration:

1. Re-authenticate with a user account that has the required permissions. Run terraform login and follow the prompts.
2. Update the currently authenticated user's team membership to grant one of the permissions listed above.
3. If you are providing credentials via a token, replace the existing token with one that has the required permissions. This applies to tokens set in:
   • The token argument of the backend or cloud block.
   • The TF_TOKEN_<hostname> environment variable.
   • The credentials block in the CLI configuration file.

Additional Information

• Migrating to HCP Terraform or Terraform Enterprise
• Manage Access to Workspaces