hashicorp/terraform · error

Error unlocking Alibaba Cloud OSS state file: Lock ID: %s E

Error message

Error unlocking Alibaba Cloud OSS state file:

Lock ID: %s
Error message: %#v

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

What it means

The stateUnlockError template (backend_state.go:200-208) used inside StateMgr's lockUnlock helper (backend_state.go:155-159). It fires when stateMgr.Unlock(lockId) fails after the backend already acquired an init lock for a new workspace. The error tells the user the lock may be left dangling and points them at force-unlock.

Source

Thrown at internal/backend/remote-state/oss/backend_state.go:157

		if s == name {
			exists = true
			break
		}
	}
	// We need to create the object so it's listed by States.
	if !exists {
		// take a lock on this state while we write it
		lockInfo := statemgr.NewLockInfo()
		lockInfo.Operation = "init"
		lockId, err := client.Lock(lockInfo)
		if err != nil {
			return nil, diags.Append(fmt.Errorf("failed to lock OSS state: %s", err))
		}

		// Local helper function so we can call it multiple places
		lockUnlock := func(e error) error {
			if err := stateMgr.Unlock(lockId); err != nil {
				return fmt.Errorf(strings.TrimSpace(stateUnlockError), lockId, err)
			}
			return e
		}

		// Grab the value
		if err := stateMgr.RefreshState(); err != nil {
			err = lockUnlock(err)
			return nil, diags.Append(err)
		}

		// If we have no state, we have to create an empty state
		if v := stateMgr.State(); v == nil {
			if err := stateMgr.WriteState(states.NewState()); err != nil {
				err = lockUnlock(err)
				return nil, diags.Append(err)
			}
			if err := stateMgr.PersistState(nil); err != nil {
				err = lockUnlock(err)

View on GitHub (pinned to c9def3e214)

Solutions

1. Record the Lock ID from the message and run terraform force-unlock <LOCK_ID>.
2. Verify the OTS table still exists and credentials retain tablestore:DeleteRow.
3. If the original failure was transient, re-run terraform init after force-unlock.
4. Audit for concurrent processes that removed the lock row out from under this run.

Example fix

# the error prints:
#   Error unlocking Alibaba Cloud OSS state file:
#   Lock ID: 7e8f...
# fix:
terraform force-unlock 7e8f...

// After a failed init, programmatically check for a dangling lock and offer force-unlock.
func recoverInit(statePath string) error {
    info, err := getLockInfo()
    if err == nil && info.ID != "" {
        fmt.Printf("dangling lock %s; run terraform force-unlock %s\n", info.ID, info.ID)
    }
    return nil
}

// Parse the Lock ID from the message and run force-unlock, then re-init.
re := regexp.MustCompile(`Lock ID:\s*([A-Za-z0-9-]+)`)
if m := re.FindStringSubmatch(err.Error()); m != nil {
    runForceUnlock(m[1])
}

When it happens

Trigger: During first-use state initialization, after successfully Lock()-ing, a subsequent step (RefreshState/WriteState/PersistState) fails and the cleanup Unlock() also fails, so the error returned to the user combines the original failure with this unlock-failure message naming the lockId.

Common situations: OTS transient failure exactly during the unlock window; OTS table deleted mid-init; RAM permissions changed mid-run; lock row was concurrently removed by another force-unlock, making the conditional delete behave unexpectedly.

Related errors

• error describing table store %s: %#v
• failed to lock OSS state: %s
• invoking PutRow got an error: %#v
• getting lock info got an error: %#v
• failed to retrieve lock info: %s

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/b570370c2dc11344. Report an issue: GitHub.