{"record":{"id":"f8d18730dc8200ed","repo":"hashicorp/terraform","slug":"unlocking-the-state-file-on-tencentcloud-cos-back","errorCode":null,"errorMessage":"\nUnlocking the state file on TencentCloud cos backend failed:\n\nError message: %v\nLock ID (gen): %s\n\nYou may have to force-unlock this state in order to use it again.\nThe TencentCloud backend acquires a lock during initialization\nto ensure the initial state file is created.\n","messagePattern":"\nUnlocking the state file on TencentCloud cos backend failed:\n\nError message: (.+?)\nLock ID \\(gen\\): (.+?)\n\nYou may have to force-unlock this state in order to use it again\\.\nThe TencentCloud backend acquires a lock during initialization\nto ensure the initial state file is created\\.\n","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote-state/cos/backend_state.go","lineNumber":121,"sourceCode":"\t\t\tbreak\n\t\t}\n\t}\n\n\tif !exists {\n\t\tlog.Printf(\"[DEBUG] workspace %v not exists\", name)\n\n\t\t// take a lock on this state while we write it\n\t\tlockInfo := statemgr.NewLockInfo()\n\t\tlockInfo.Operation = \"init\"\n\t\tlockId, err := c.Lock(lockInfo)\n\t\tif err != nil {\n\t\t\treturn nil, diags.Append(fmt.Errorf(\"Failed to lock cos state: %s\", err))\n\t\t}\n\n\t\t// Local helper function so we can call it multiple places\n\t\tlockUnlock := func(e error) error {\n\t\t\tif err := stateMgr.Unlock(lockId); err != nil {\n\t\t\t\treturn fmt.Errorf(unlockErrMsg, err, lockId)\n\t\t\t}\n\t\t\treturn e\n\t\t}\n\n\t\t// Grab the value\n\t\tif err := stateMgr.RefreshState(); err != nil {\n\t\t\terr = lockUnlock(err)\n\t\t\treturn nil, diags.Append(err)\n\t\t}\n\n\t\t// If we have no state, we have to create an empty state\n\t\tif v := stateMgr.State(); v == nil {\n\t\t\tif err := stateMgr.WriteState(states.NewState()); err != nil {\n\t\t\t\terr = lockUnlock(err)\n\t\t\t\treturn nil, diags.Append(err)\n\t\t\t}\n\t\t\tif err := stateMgr.PersistState(nil); err != nil {\n\t\t\t\terr = lockUnlock(err)","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/backend/remote-state/cos/backend_state.go#L103-L139","documentation":"Mirror of 181 for COS. After taking the init lock and failing on RefreshState/WriteState/PersistState, the lockUnlock helper calls stateMgr.Unlock(lockId); if that unlock itself fails (formatted by unlockErrMsg), this error is raised and the user is told to force-unlock.","triggerScenarios":"In StateMgr init, one of RefreshState/WriteState/PersistState errors; lockUnlock's stateMgr.Unlock(lockId) returns non-nil; the helper returns fmt.Errorf(unlockErrMsg, err, lockId).","commonSituations":"COS connectivity lost mid-init; lock object deleted externally before unlock; COS 5xx during DeleteObject on the lock file; lock id mismatch because the lock was already released or re-acquired.","solutions":["Capture the Lock ID (gen) printed in the message and run `terraform force-unlock <LOCK_ID>`.","Inspect the lock object at the lock file path in the bucket; remove it manually if stale.","Verify COS service status and credentials before retrying."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// If init failed with a dangling lock, attempt recovery once.\nsm, diags := backend.StateMgr(name)\nif diags.HasErrors() {\n    msg := diags.Err().Error()\n    if strings.Contains(msg, \"force-unlock\") {\n        if id := extractLockID(msg); id != \"\" {\n            log.Printf(\"init left dangling lock %s; attempting force-unlock\", id)\n            if _, uerr := sm.Unlock(id); uerr != nil {\n                return fmt.Errorf(\"manual recovery required: %w\", uerr)\n            }\n        }\n    }\n    return diags.Err()\n}","preventionTips":["Keep COS reachable from the Terraform host; check COS status before runs.","Don't revoke COS credentials mid-operation.","Have a force-unlock runbook and capture lock IDs in CI logs.","Audit the bucket for orphaned lock files periodically."],"tags":["cos","tencent-cloud","state-locking","recovery","backend"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}