{"record":{"id":"fe6b87bae5cf0c49","repo":"hashicorp/terraform","slug":"errchecksumdoesnotmatch","errorCode":"ErrChecksumDoesNotMatch","errorMessage":"downloaded archive does not match the release checksum","messagePattern":"downloaded archive does not match the release checksum","errorType":"exception","errorClass":"ErrChecksumDoesNotMatch","httpStatus":null,"severity":"critical","filePath":"internal/releaseauth/checksum.go","lineNumber":28,"sourceCode":"\t\"fmt\"\n\t\"io\"\n\t\"log\"\n\t\"os\"\n)\n\n// ChecksumAuthentication is an archive Authenticator that ensures a given file\n// matches a SHA-256 checksum. It is important to verify the authenticity of the\n// given checksum prior to using this Authenticator.\ntype ChecksumAuthentication struct {\n\tAuthenticator\n\n\texpected        SHA256Hash\n\tarchiveLocation string\n}\n\n// ErrChecksumDoesNotMatch is the error returned when the archive checksum does\n// not match the given checksum.\nvar ErrChecksumDoesNotMatch = errors.New(\"downloaded archive does not match the release checksum\")\n\n// NewChecksumAuthentication creates an instance of ChecksumAuthentication with the given\n// checksum and file location.\nfunc NewChecksumAuthentication(expected SHA256Hash, archiveLocation string) *ChecksumAuthentication {\n\treturn &ChecksumAuthentication{\n\t\texpected:        expected,\n\t\tarchiveLocation: archiveLocation,\n\t}\n}\n\nfunc (a ChecksumAuthentication) Authenticate() error {\n\tf, err := os.Open(a.archiveLocation)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to open downloaded archive: %w\", err)\n\t}\n\tdefer f.Close()\n\n\th := sha256.New()","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/releaseauth/checksum.go#L10-L46","documentation":"ErrChecksumDoesNotMatch is a sentinel from ChecksumAuthentication.Authenticate: it computes the SHA-256 of the downloaded archive on disk and compares it byte-for-byte against the expected SHA256Hash. A mismatch means the bytes that arrived are not the bytes the checksum file (SHA256SUMS) attests to, indicating corruption or tampering after the checksum source was authenticated.","triggerScenarios":"Returned at internal/releaseauth/checksum.go:55 when bytes.Equal(gotHash, a.expected[:]) is false. The Authenticator is constructed via NewChecksumAuthentication(expected, archiveLocation) and is meant to run only after the expected checksum's authenticity is independently verified (e.g. by SignatureAuthentication).","commonSituations":"A truncated/partial download (network drop, disk full). A transparent proxy or corporate mirror rewriting the archive. Concurrent/aborted download leaving a partial file. A mismatched SHA256SUMS file used as the expected value. Disk/memory corruption. A man-in-the-middle that modified bytes (signature check should also then fail).","solutions":["Delete the cached/partial archive and re-download with `terraform init -upgrade` or by clearing the plugin cache.","Verify the expected checksum actually corresponds to this archive version (re-fetch SHA256SUMS for the exact release).","Disable or bypass any corporate proxy/mirror that may be altering bytes; confirm via a direct curl and sha256sum compare.","Check free disk space and filesystem integrity if corruption is suspected.","If both signature and checksum fail, treat as a potential supply-chain incident and re-verify against the publisher's published sums."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Pre-check is impossible (must hash the file first), but you can verify the\n// expected checksum string is well-formed before constructing the Authenticator.\nif _, err := releaseauth.SHA256FromHex(expectedHex); err != nil {\n    return fmt.Errorf(\"bad expected checksum: %w\", err)\n}","typeGuard":"func isChecksumMismatch(err error) bool {\n    return errors.Is(err, releaseauth.ErrChecksumDoesNotMatch)\n}","tryCatchPattern":"if err := auth.Authenticate(); err != nil {\n    if errors.Is(err, releaseauth.ErrChecksumDoesNotMatch) {\n        // delete partial file and re-download once\n        os.Remove(archiveLocation)\n        return redownload()\n    }\n    return err\n}","preventionTips":["Always run SignatureAuthentication before ChecksumAuthentication so the expected hash is trusted.","Clear the plugin cache on integrity failures.","Compare a manual sha256sum of the file against the published sums when in doubt."],"tags":["release-auth","checksum","sha256","integrity","download"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}