{"record":{"id":"36281c8b414772a3","repo":"hashicorp/terraform","slug":"failed-to-open-file-at-v-checksum-mismatch-s","errorCode":null,"errorMessage":"failed to open file at %v: checksum mismatch, %s != %s","messagePattern":"failed to open file at (.+?): checksum mismatch, (.+?) != (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/backend/remote-state/cos/client.go","lineNumber":219,"sourceCode":"\tchecksum = rsp.Header.Get(\"X-Cos-Meta-Md5\")\n\tlog.Printf(\"[DEBUG] getObject %s: checksum: %s\", cosFile, checksum)\n\tif len(checksum) != 32 {\n\t\terr = fmt.Errorf(\"failed to open file at %v: checksum %s invalid\", cosFile, checksum)\n\t\treturn\n\t}\n\n\texists = true\n\tdata, err = ioutil.ReadAll(rsp.Body)\n\tlog.Printf(\"[DEBUG] getObject %s: data length: %d\", cosFile, len(data))\n\tif err != nil {\n\t\terr = fmt.Errorf(\"failed to open file at %v: %v\", cosFile, err)\n\t\treturn\n\t}\n\n\tcheck := fmt.Sprintf(\"%x\", md5.Sum(data))\n\tlog.Printf(\"[DEBUG] getObject %s: check: %s\", cosFile, check)\n\tif check != checksum {\n\t\terr = fmt.Errorf(\"failed to open file at %v: checksum mismatch, %s != %s\", cosFile, check, checksum)\n\t\treturn\n\t}\n\n\treturn\n}\n\n// putObject put object to remote\nfunc (c *remoteClient) putObject(cosFile string, data []byte) error {\n\topt := &cos.ObjectPutOptions{\n\t\tObjectPutHeaderOptions: &cos.ObjectPutHeaderOptions{\n\t\t\tXCosMetaXXX: &http.Header{\n\t\t\t\t\"X-Cos-Meta-Md5\": []string{fmt.Sprintf(\"%x\", md5.Sum(data))},\n\t\t\t},\n\t\t},\n\t\tACLHeaderOptions: &cos.ACLHeaderOptions{\n\t\t\tXCosACL: c.acl,\n\t\t},\n\t}","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/backend/remote-state/cos/client.go#L201-L237","documentation":"Raised by getObject() when the MD5 computed over the downloaded bytes does not equal the 'X-Cos-Meta-Md5' stored when the object was written. This is an active integrity check: the object's content was altered on the wire or in storage since it was uploaded. The backend treats any mismatch as corrupt state and refuses to load it.","triggerScenarios":"At client.go:216-219, md5.Sum(data) is compared to the stored checksum; mismatch occurs when bytes differ — silent corruption in COS, a proxy modifying the stream, an object overwritten by a non-Terraform process that changed content but not the header, or an in-flight concurrent write that produced a torn read.","commonSituations":"Two Terraform runs writing the same key concurrently without locking; an external process or lifecycle rule rewrote the object; encoding/corruption from a misconfigured CDN or transparent proxy (e.g. gzip mangling); rare bit-rot or storage-tier corruption; an object uploaded by a tool that set a wrong X-Cos-Meta-Md5.","solutions":["Restore from the last known-good state backup ('terraform state push' a local copy or a prior version from COS versioning/bucket backup).","Verify no concurrent Terraform runs or external writers are targeting the same key; enable state locking and ensure the lock tag is functional.","Compare the downloaded bytes against a known-good copy to confirm corruption vs. a legitimately changed object, then re-push the correct state.","If a proxy/CDN is in the path, bypass it or fix content-encoding handling so the body is delivered byte-for-byte."],"exampleFix":"# recover from a corrupt state object\nterraform state pull > /tmp/check.tfstate.json   # likely fails with checksum mismatch\n# restore a known-good copy and re-push\nmd5sum /tmp/good.tfstate.json\nterraform state push --force /tmp/good.tfstate.json","handlingStrategy":"validation","validationCode":"// After download, recompute md5 and compare before using the bytes.\nfunc verifyStateIntegrity(data []byte, checksum string) error {\n    got := fmt.Sprintf(\"%x\", md5.Sum(data))\n    if len(checksum) != 32 {\n        return fmt.Errorf(\"missing/invalid stored checksum\")\n    }\n    if got != checksum {\n        return fmt.Errorf(\"checksum mismatch %s != %s\", got, checksum)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if _, _, _, err := c.getObject(c.stateFile); err != nil {\n    if strings.Contains(err.Error(), \"checksum mismatch\") {\n        // DO NOT overwrite; restore from backup instead\n    }\n}","preventionTips":["Keep versioning/backup on the state bucket so a corrupt object can be rolled back.","Never let two writers touch the same key; rely on the lock.","Investigate any proxy/CDN in the data path that may alter bytes."],"tags":["cos","tencent-cloud","checksum","data-integrity","corruption","state","concurrency"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T20:17:04.800Z"}