{"record":{"id":"1bf3ec3040166b5d","repo":"hashicorp/terraform","slug":"failed-to-load-the-backend-state-file-when-prepari","errorCode":null,"errorMessage":"Failed to load the backend state file when preparing to update it: %s","messagePattern":"Failed to load the backend state file when preparing to update it: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/state_migrate.go","lineNumber":428,"sourceCode":"\treturn strings.TrimSpace(helpText)\n}\n\nfunc (c *StateMigrateCommand) Synopsis() string {\n\treturn \"Migrate the state from one location to another\"\n}\n\nconst (\n\tMigrationSource      = \"source\"\n\tMigrationDestination = \"destination\"\n)\n\nfunc (c *StateMigrateCommand) updateBackendStateFile(s *workdir.BackendStateFile) tfdiags.Diagnostics {\n\tvar diags tfdiags.Diagnostics\n\n\tstatePath := filepath.Join(c.DataDir(), DefaultStateFilename)\n\tsMgr := &clistate.LocalState{Path: statePath}\n\tif err := sMgr.RefreshState(); err != nil {\n\t\tdiags = diags.Append(fmt.Errorf(\"Failed to load the backend state file when preparing to update it: %s\", err))\n\t\treturn diags\n\t}\n\n\tif err := sMgr.WriteState(s); err != nil {\n\t\tdiags = diags.Append(errBackendWriteSavedDiag(err))\n\t\treturn diags\n\t}\n\tif err := sMgr.PersistState(); err != nil {\n\t\tdiags = diags.Append(errBackendWriteSavedDiag(err))\n\t\treturn diags\n\t}\n\n\treturn diags\n}\n\nfunc (c *StateMigrateCommand) getDestinationStateStoreProviderRequirements(provider addrs.Provider, configReqs *configs.RequiredProviders) (providerreqs.Requirements, tfdiags.Diagnostics) {\n\tvar diags tfdiags.Diagnostics\n\treq := make(providerreqs.Requirements, 1)","sourceCodeStart":410,"sourceCodeEnd":446,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/command/state_migrate.go#L410-L446","documentation":"Thrown by updateBackendStateFile during the post-migration step: it loads .terraform/terraform.tfstate via clistate.LocalState.RefreshState to update it with the new backend metadata, and RefreshState fails. The %s is the underlying read/parse error. This runs only after the migration itself succeeded, so a failure here leaves the local state file inconsistent with the just-completed migration.","triggerScenarios":"After a successful state migration, when reading .terraform/terraform.tfstate fails: the file was deleted/moved by another process, is corrupted JSON, has permission issues, or the lock acquisition fails.","commonSituations":"Another process or editor overwrote/deleted terraform.tfstate mid-migration; antivirus/backup tools locking the file on Windows/NFS; a previous run left a corrupt state file; permission change between source and target UIDs.","solutions":["Check .terraform/terraform.tfstate exists and is valid JSON: `terraform state pull` or inspect the file.","Restore from the backup (.terraform/terraform.tfstate.backup) if the local state is corrupt.","Ensure no concurrent Terraform process or editor touches terraform.tfstate, then re-run migrate.","Fix file permissions so the running user can read/write .terraform/terraform.tfstate."],"exampleFix":"# before: local state file corrupted mid-migration\nls .terraform/terraform.tfstate\n# (missing or invalid)\n\n# after: restore backup, retry\ncp .terraform/terraform.tfstate.backup .terraform/terraform.tfstate\nterraform state migrate","handlingStrategy":"validation","validationCode":"// before the post-migration update, sanity-check the local state file.\nfunc stateFileReadable(path string) error {\n    f, err := os.Open(path)\n    if err != nil { return err }\n    defer f.Close()\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Ensure nothing else edits/removes terraform.tfstate during a migration.","Keep .terraform/terraform.tfstate.backup intact as a recovery source.","Avoid running state migrations on filesystems with aggressive AV/backup locking.","Run migrations as a single owner of the workspace directory."],"tags":["state-migrate","local-state","filesystem","consistency"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T21:17:07.882Z"}