What causes "archive has incorrect checksum %s (expected %s)" in hashicorp/terraform?

Re-download from the authoritative registry or a corrected mirror after purging the cache.

archive has incorrect checksum %s (expected %s)

Error message

archive has incorrect checksum %s (expected %s)

What it means

Integrity failure from archiveHashAuthentication.AuthenticatePackage. PackageHashLegacyZipSHA succeeded but the computed 'zh:' hash differs from HashLegacyZipSHAFromSHA(a.WantSHA256Sum). The downloaded .zip's SHA256 does not match the checksum declared by the registry/mirror for this provider version.

Source

Thrown at internal/getproviders/package_authentication.go:315

func NewArchiveChecksumAuthentication(platform Platform, wantSHA256Sum [sha256.Size]byte) PackageAuthentication {
	return archiveHashAuthentication{platform, wantSHA256Sum}
}

func (a archiveHashAuthentication) AuthenticatePackage(localLocation PackageLocation) (*PackageAuthenticationResult, error) {
	archiveLocation, ok := localLocation.(PackageLocalArchive)
	if !ok {
		// A source should not use this authentication type for non-archive
		// locations.
		return nil, fmt.Errorf("cannot check archive hash for non-archive location %s", localLocation)
	}

	gotHash, err := PackageHashLegacyZipSHA(archiveLocation)
	if err != nil {
		return nil, fmt.Errorf("failed to compute checksum for %s: %s", archiveLocation, err)
	}
	wantHash := HashLegacyZipSHAFromSHA(a.WantSHA256Sum)
	if gotHash != wantHash {
		return nil, fmt.Errorf("archive has incorrect checksum %s (expected %s)", gotHash, wantHash)
	}
	return &PackageAuthenticationResult{result: verifiedChecksum}, nil
}

func (a archiveHashAuthentication) AcceptableHashes() []Hash {
	return []Hash{HashLegacyZipSHAFromSHA(a.WantSHA256Sum)}
}

type matchingChecksumAuthentication struct {
	Document      []byte
	Filename      string
	WantSHA256Sum [sha256.Size]byte
}

// NewMatchingChecksumAuthentication returns a PackageAuthentication
// implementation that scans a registry-provided SHA256SUMS document for a
// specified filename, and compares the SHA256 hash against the expected hash.
// This is necessary to ensure that the signed SHA256SUMS document matches the

View on GitHub (pinned to c9def3e214)

Solutions

Re-download from the authoritative registry or a corrected mirror after purging the cache.
If you operate the mirror, ensure the served .zip is byte-identical to the upstream release and republish its SHA256.
Avoid repackaging zips (which invalidates 'zh:' hashes); prefer the 'h1:' content hash if you must repack.
Pin the provider version to a release whose published checksum matches the artifact you can actually fetch.

Example fix

// before: mirror served a repackaged zip
Error: archive has incorrect checksum zh:aaa... (expected zh:bbb...)
// after: purge mirror cache and serve upstream zip
$ rm -rf ~/.cache/terraform/plugin-cache/<provider> && terraform init

Defensive patterns

Strategy: validation

Validate before calling

// Compute the zip hash and compare to expected before relying on it.
got, err := getproviders.PackageHashLegacyZipSHA(archiveLoc)
if err != nil { return err }
want := getproviders.HashLegacyZipSHAFromSHA(shaSum)
if got != want { return fmt.Errorf("zip hash mismatch: got %s want %s", got, want) }

Try / catch

_, err := auth.AuthenticatePackage(loc)
if err != nil && strings.Contains(err.Error(), "archive has incorrect checksum") {
    // artifact drift: re-fetch from authoritative source, never weaken the check.
}
return err

Prevention

Never repack provider zips; serve upstream bytes verbatim.
Validate mirror checksums against the registry periodically.
Pin to versions whose published zip hash you can independently verify.

When it happens

Trigger: gotHash != wantHash at line 314, error at 315. The archive is readable but its bytes do not hash to the expected SHA256 sum that was passed into NewArchiveChecksumAuthentication.

Common situations: Mirror serves a different/older .zip than the one the checksum was computed from. A truncated or re-zipped download (re-compression changes the archive bytes even if contents match, breaking the legacy zip hash). CDN serving a stale cached artifact. Tampering/MITM altering the archive in transit.

Related errors

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