{"record":{"id":"7022c3a97e6df356","repo":"hashicorp/terraform","slug":"unlocking-the-state-file-on-tencentcloud-cos-backe","errorCode":null,"errorMessage":"Unlocking 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":"Unlocking 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":"console","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/c9def3e214014c1188faabfc4a5bde5095139765/internal/backend/remote-state/cos/backend_state.go#L103-L139","documentation":"The unlockErrMsg constant (cos/backend_state.go:121), emitted by the lockUnlock() helper inside StateMgr() when the cleanup Unlock of the initialization lock itself fails. It warns that the state is now locked and must be force-unlocked before it can be used again, and includes the lock ID (gen) so the user knows what to unlock.","triggerScenarios":"During StateMgr() init, after a write/persist failure, lockUnlock() calls stateMgr.Unlock(lockId) which returns an error; the formatted message is returned wrapping that error.","commonSituations":"Transient COS failure during init cleanup; credentials expired mid-init; the lock object was already removed by a concurrent process so the unlock call errors; permissions to delete the lock object are missing.","solutions":["Run `terraform force-unlock <Lock ID (gen)>` using the ID printed in the message.","Confirm the COS credentials still have object-delete and tag-delete permissions.","Manually remove the lock file object and the tencentcloud-terraform-lock tag if force-unlock also fails.","Re-run `terraform init` once the lock is cleared."],"exampleFix":"// error includes: Lock ID (gen): <id>\nterraform force-unlock <id>\nterraform init","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// After a failed init, attempt force-unlock using the reported lock ID\nif diags.HasErrors() && strings.Contains(diags.Err().Error(), \"Unlocking the state file on TencentCloud cos backend failed\") {\n    id := extractLockID(diags.Err().Error())\n    _ = forceUnlockCos(id) // terraform force-unlock <id>\n}","preventionTips":["Run `terraform force-unlock <Lock ID (gen)>` promptly when this message appears.","Verify COS delete permissions so future cleanups succeed.","Avoid killing terraform mid-init, which leaves locks behind."],"tags":["cos","tencentcloud","lock","unlock","force-unlock","init","stuck-state"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}