hashicorp/terraform · error

ziphash scheme ("zh:" prefix) is not supported for unpacked

Error message

ziphash scheme ("zh:" prefix) is not supported for unpacked provider packages

What it means

Raised in PackageMatchesHash (internal/getproviders/hash.go:122). A hash with the 'zh:' (HashSchemeZip / legacy zip-SHA) scheme was supplied, but the package location is an unpacked directory (PackageLocalDir), not a .zip archive (PackageLocalArchive). Legacy zip hashes are computed over the original archive bytes, so they can only be verified when the archive is still present. The function refuses to silently skip and returns this explicit error.

Source

Thrown at internal/getproviders/hash.go:122

// if others are introduced in future PackageMatchesHash may accept multiple
// formats, and may generate errors for any formats that become obsolete.
//
// PackageMatchesHash can be used only with the two local package location types
// PackageLocalDir and PackageLocalArchive, because it needs to access the
// contents of the indicated package in order to compute the hash. If given
// a non-local location this function will always return an error.
func PackageMatchesHash(loc PackageLocation, want providerreqs.Hash) (bool, error) {
	switch want.Scheme() {
	case HashScheme1:
		got, err := PackageHashV1(loc)
		if err != nil {
			return false, err
		}
		return got == want, nil
	case HashSchemeZip:
		archiveLoc, ok := loc.(PackageLocalArchive)
		if !ok {
			return false, fmt.Errorf(`ziphash scheme ("zh:" prefix) is not supported for unpacked provider packages`)
		}
		got, err := PackageHashLegacyZipSHA(archiveLoc)
		if err != nil {
			return false, err
		}
		return got == want, nil
	default:
		return false, fmt.Errorf("unsupported hash format (this may require a newer version of Terraform)")
	}
}

// PackageMatchesAnyHash returns true if the package at the given location
// matches at least one of the given hashes, or false otherwise.
//
// If it cannot read from the given location, PackageMatchesAnyHash returns an
// error. Unlike the singular PackageMatchesHash, PackageMatchesAnyHash
// considers unsupported hash formats as successfully non-matching, rather
// than returning an error.

View on GitHub (pinned to c9def3e214)

Solutions

1. Supply or also accept an 'h1:' content hash (HashScheme1), which works for both unpacked dirs and archives.
2. Keep the original .zip archive and pass a PackageLocalArchive location when you must verify a zh: hash.
3. Use PackageMatchesAnyHash instead, which gracefully treats an incompatible scheme/location combination as a non-match rather than an error.

Example fix

// before
ok, err := PackageMatchesHash(PackageLocalDir("/cache/hashicorp/aws"), zhHash)
// after
ok, err := PackageMatchesHash(PackageLocalArchive("/cache/hashicorp/aws.zip"), zhHash)

// Match the hash scheme to the location type before verifying.
func canVerifyZipHash(loc PackageLocation) bool {
	_, ok := loc.(PackageLocalArchive)
	return ok
}

// Narrow a PackageLocation to a zip-backed archive before a zh: check.
func asArchive(loc PackageLocation) (PackageLocalArchive, bool) {
	a, ok := loc.(PackageLocalArchive)
	return a, ok
}

if _, ok := loc.(PackageLocalArchive); !ok && want.Scheme() == HashSchemeZip {
    // Skip zh: verification for unpacked dirs; use PackageMatchesAnyHash.
    return false, nil
}

When it happens

Trigger: Verifying an unpacked provider cache directory against a lockfile or lock entry that only carries a 'zh:' hash. The type assertion loc.(PackageLocalArchive) fails because loc is a PackageLocalDir.

Common situations: A lockfile written by an old Terraform containing only zh: hashes, used against an unpacked cache; a custom verification routine that pairs a zh: hash with a directory location; providers cached as unpacked directories by default.

Related errors

• unsupported hash format (this may require a newer version of
• this version of Terraform does not support any of the checks
• Attempted to initialize pluggable state with a nil provider
• Attempted to initialize pluggable state with an empty string
• no supported plugins for protocol 0

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