{"record":{"id":"8b151127214a631e","repo":"hashicorp/terraform","slug":"unsupported-hash-format-this-may-require-a-newer","errorCode":null,"errorMessage":"unsupported hash format (this may require a newer version of Terraform)","messagePattern":"unsupported hash format \\(this may require a newer version of Terraform\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/getproviders/hash.go","lineNumber":130,"sourceCode":"\tswitch want.Scheme() {\n\tcase HashScheme1:\n\t\tgot, err := PackageHashV1(loc)\n\t\tif err != nil {\n\t\t\treturn false, err\n\t\t}\n\t\treturn got == want, nil\n\tcase HashSchemeZip:\n\t\tarchiveLoc, ok := loc.(PackageLocalArchive)\n\t\tif !ok {\n\t\t\treturn false, fmt.Errorf(`ziphash scheme (\"zh:\" prefix) is not supported for unpacked provider packages`)\n\t\t}\n\t\tgot, err := PackageHashLegacyZipSHA(archiveLoc)\n\t\tif err != nil {\n\t\t\treturn false, err\n\t\t}\n\t\treturn got == want, nil\n\tdefault:\n\t\treturn false, fmt.Errorf(\"unsupported hash format (this may require a newer version of Terraform)\")\n\t}\n}\n\n// PackageMatchesAnyHash returns true if the package at the given location\n// matches at least one of the given hashes, or false otherwise.\n//\n// If it cannot read from the given location, PackageMatchesAnyHash returns an\n// error. Unlike the singular PackageMatchesHash, PackageMatchesAnyHash\n// considers unsupported hash formats as successfully non-matching, rather\n// than returning an error.\n//\n// PackageMatchesAnyHash can be used only with the two local package location\n// types PackageLocalDir and PackageLocalArchive, because it needs to access the\n// contents of the indicated package in order to compute the hash. If given\n// a non-local location this function will always return an error.\nfunc PackageMatchesAnyHash(loc PackageLocation, allowed []providerreqs.Hash) (bool, error) {\n\t// It's likely that we'll have multiple hashes of the same scheme in\n\t// the \"allowed\" set, in which case we'll avoid repeatedly re-reading the","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/getproviders/hash.go#L112-L148","documentation":"`PackageMatchesHash` switches on `want.Scheme()` and only handles `HashScheme1` (`h1:`) and `HashSchemeZip` (`zh:`). Any other scheme falls into the `default` arm and produces this message, hinting that the running Terraform is older than whatever scheme was introduced. It is a forward-compatibility guard.","triggerScenarios":"A `Hash` with an unknown scheme prefix is passed to `PackageMatchesHash`; switch hits the `default` at hash.go:130.","commonSituations":"A newer Terraform wrote a lock file with a new hash scheme, then an older Terraform reads it; a hand-edited lock file with a typo'd prefix; experimental/custom hash schemes.","solutions":["Upgrade Terraform/OpenTofu to a version that understands the new hash scheme.","Remove the unknown hash lines from the lock file and regenerate with `terraform providers lock`.","Use `PackageMatchesAnyHash` which silently treats unknown schemes as non-matching."],"exampleFix":"// before\nhashes:\n  - h9:abcdef...   # unknown scheme\n// after: regenerate\n$ terraform providers lock -platform=linux_amd64","handlingStrategy":"validation","validationCode":"// Reject unknown schemes before calling PackageMatchesHash\nswitch want.Scheme() {\ncase HashScheme1, HashSchemeZip:\n    return PackageMatchesHash(loc, want)\ndefault:\n    log.Printf(\"[WARN] unknown hash scheme %q; treating as non-match\", want.Scheme())\n    return false, nil\n}","typeGuard":"// isKnownScheme narrows to schemes this build understands\nfunc isKnownScheme(s HashScheme) bool {\n    return s == HashScheme1 || s == HashSchemeZip\n}","tryCatchPattern":"ok, err := PackageMatchesHash(loc, want)\nif err != nil && strings.Contains(err.Error(), \"unsupported hash format\") {\n    // upgrade required, or treat as non-match\n    return PackageMatchesAnyHash(loc, []Hash{want})\n}","preventionTips":["Keep Terraform/OpenTofu versions consistent across the team to avoid new schemes.","Regenerate the lock file after upgrades.","Use `PackageMatchesAnyHash` where forward compatibility matters.","Document the hash scheme in use in repo README."],"tags":["hash","lock-file","version-mismatch","forward-compat"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}