{"record":{"id":"9ea9eed9577140c9","repo":"hashicorp/terraform","slug":"this-working-directory-uses-legacy-remote-state-an","errorCode":null,"errorMessage":"this working directory uses legacy remote state and so must first be upgraded using Terraform v0.9","messagePattern":"this working directory uses legacy remote state and so must first be upgraded using Terraform v0\\.9","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/workdir/backend_state.go","lineNumber":108,"sourceCode":"\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\")\n\t}\n\tif stateFile.StateStore != nil && stateFile.StateStore.ProviderSupplyMode == \"\" {\n\t\t// Check for this, as lacking this data can cause problems later when an empty provider version\n\t\t// is encountered. This error will make debugging much easier.\n\t\treturn nil, fmt.Errorf(\"encountered a malformed backend state file with a 'state_store' block that is missing the required 'provider_supply_mode' property\")\n\t}\n\n\treturn &stateFile, nil\n}\n\nfunc EncodeBackendStateFile(f *BackendStateFile) ([]byte, error) {\n\tf.Version = 3 // we only support version 3\n\tf.TFVersion = version.SemVer.String()\n\n\tswitch {","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/command/workdir/backend_state.go#L90-L126","documentation":"ParseBackendStateFile decoded the file successfully and found a non-nil `remote` block but no `backend` block. That shape is the pre-0.9 legacy remote-state format, which the current binary cannot use directly — the user must upgrade it with Terraform v0.9 first (which converts `remote` to `backend`).","triggerScenarios":"Opening a workspace last touched by Terraform v0.8.x or earlier, where state was configured via the legacy `remote` subcommand rather than a backend block.","commonSituations":"Decades-old infrastructure workspace never migrated, archived project resurrected with a modern Terraform, training/lab environments frozen at v0.8.","solutions":["Run `terraform init` once with Terraform v0.9.x in this workspace to perform the legacy-to-backend migration, then switch to a modern binary.","If v0.9 is unavailable, discard the legacy file (rm .terraform/terraform.tfstate) and configure a fresh backend block + `terraform init`.","Migrate state to a remote backend (S3, etc.) from v0.9 first, then continue on the current version."],"exampleFix":"# step 1 — upgrade the legacy file with terraform 0.9\nterraform0.9 init\n\n# step 2 — continue with modern terraform\nterraform init","handlingStrategy":"validation","validationCode":"// detect legacy remote shape up front and steer the user to the upgrade path\nvar probe struct {\n    Backend *json.RawMessage `json:\"backend\"`\n    Remote  *json.RawMessage `json:\"remote\"`\n}\n_ = json.Unmarshal(src, &probe)\nif probe.Backend == nil && probe.Remote != nil {\n    return nil, errors.New(\"legacy remote state detected; run `terraform init` under v0.9.x to migrate, then re-init on the current version\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When reviving old workspaces, run them once on v0.9 before going modern.","Prefer remote backends (S3, etc.) over legacy remote state."],"tags":["backend","legacy-migration","version","init"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}