{"record":{"id":"b43af56161beacda","repo":"hashicorp/terraform","slug":"unsupported-backend-state-version-d-you-may-need","errorCode":null,"errorMessage":"unsupported backend state version %d; you may need to use Terraform CLI v%s to work in this directory","messagePattern":"unsupported backend state version (.+?); you may need to use Terraform CLI v(.+?) to work in this directory","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/workdir/backend_state.go","lineNumber":93,"sourceCode":"\ttype VersionSniff struct {\n\t\tVersion   int    `json:\"version\"`\n\t\tTFVersion string `json:\"terraform_version,omitempty\"`\n\t}\n\tvar versionSniff VersionSniff\n\terr := json.Unmarshal(src, &versionSniff)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"invalid syntax: %w\", err)\n\t}\n\tif versionSniff.Version == 0 {\n\t\t// This could either mean that it's explicitly \"version\": 0 or that\n\t\t// the version property is missing. We'll assume the latter here\n\t\t// because state snapshot version 0 was an encoding/gob binary format\n\t\t// rather than a JSON format and so it would be very weird for\n\t\t// that to show up in a JSON file.\n\t\treturn nil, fmt.Errorf(\"invalid syntax: no format version number\")\n\t}\n\tif versionSniff.Version != 3 {\n\t\treturn nil, fmt.Errorf(\"unsupported backend state version %d; you may need to use Terraform CLI v%s to work in this directory\", versionSniff.Version, versionSniff.TFVersion)\n\t}\n\n\t// If we get here then we can be sure that this file at least _thinks_\n\t// it's format version 3.\n\tvar stateFile BackendStateFile\n\terr = json.Unmarshal(src, &stateFile)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"invalid syntax: %w\", err)\n\t}\n\tif stateFile.Backend == nil && stateFile.Remote != nil {\n\t\t// It's very unlikely to get here, but one way it could happen is\n\t\t// if this working directory was most recently used with Terraform v0.8\n\t\t// or earlier, which didn't yet include the concept of backends.\n\t\t// This error message assumes that's the case.\n\t\treturn nil, fmt.Errorf(\"this working directory uses legacy remote state and so must first be upgraded using Terraform v0.9\")\n\t}\n\tif stateFile.Backend != nil && stateFile.StateStore != nil {\n\t\treturn nil, fmt.Errorf(\"encountered a malformed backend state file that contains state for both a 'backend' and a 'state_store' block\")","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/command/workdir/backend_state.go#L75-L111","documentation":"The backend state file (.terraform/terraform.tfstate) carries a numeric 'version' field. ParseBackendStateFile at backend_state.go:92 only accepts version 3; any other value means the file was written by a Terraform release whose on-disk format this binary cannot interpret. The message includes the terraform_version recorded in the file so you can install that exact release to read the directory.","triggerScenarios":"ParseBackendStateFile is called on bytes whose JSON 'version' field is not 3 — e.g. version 4 from a newer Terraform, or version 1/2 from a very old release. The version-sniff struct at backend_state.go:75 decodes 'version' first, then line 92 rejects non-3 values.","commonSituations":"Running an older pinned Terraform CLI in a directory last touched by a newer Terraform that bumped the format version; CI using a pinned older Terraform against .terraform/ artifacts written by a teammate's newer local install; switching tfenv versions mid-project.","solutions":["Install and switch to the exact Terraform CLI version printed in the error message (the file recorded it in terraform_version).","If downgrading is impossible, remove the .terraform/ directory and re-run 'terraform init' to regenerate it with the current binary.","Pin the team's Terraform version (.terraform-version / tfenv / required_version) so the format version never drifts again."],"exampleFix":"// before\n$ terraform plan   # in a dir last used by a newer Terraform\nError: unsupported backend state version 4; you may need to use Terraform CLI v1.10.0\n\n// after\n$ tfenv use 1.10.0\n$ terraform init\n$ terraform plan","handlingStrategy":"validation","validationCode":"// Sniff the version before a full parse so you can branch gracefully.\nfunc backendStateFileVersion(src []byte) (int, error) {\n    var sniff struct{ Version int `json:\"version\"` }\n    if err := json.Unmarshal(src, &sniff); err != nil {\n        return 0, err\n    }\n    return sniff.Version, nil\n}\n\nver, _ := backendStateFileVersion(src)\nif ver != 3 {\n    // surface a friendly 'wrong Terraform version' message instead of a raw parse error\n}","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Pin the Terraform version across the team via required_version, .terraform-version, or tfenv.","Never commit the .terraform/ directory; let each environment re-init with its own binary.","Avoid running multiple Terraform major versions against the same working directory."],"tags":["terraform","state","version-mismatch","workdir"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T20:17:04.800Z"}