{"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":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/state_migrate.go","lineNumber":435,"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":417,"sourceCodeEnd":453,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/command/state_migrate.go#L417-L453","documentation":"Thrown in updateBackendStateFile by clistate.LocalState.RefreshState() on the local state file at DataDir()/terraform.tfstate. This happens just before Terraform tries to write the new backend state marker. Failure means the local state file is missing, unreadable, or corrupt JSON at the moment of refresh.","triggerScenarios":"The local state file at <dataDir>/terraform.tfstate exists but cannot be JSON-decoded; os.Open fails (permission, ENOENT mid-flight); file is empty after a previous interrupted write.","commonSituations":"Running `terraform state migrate` with a manually truncated local state file; another process editing terraform.tfstate concurrently; permissions changed mid-run; data dir on an unreliable network mount.","solutions":["Restore terraform.tfstate from `terraform.tfstate.backup` if present.","Validate the file: `python -m json.tool terraform.tfstate`.","Ensure no other terraform process is running in the directory.","Re-run `terraform init` then re-attempt the migration."],"exampleFix":"# before\n terraform state migrate  # local state corrupt\n\n# after\n cp terraform.tfstate.backup terraform.tfstate\n terraform state migrate","handlingStrategy":"validation","validationCode":"// Pre-check the local state file is readable + valid JSON.\ndata, err := os.ReadFile(statePath)\nif err != nil { return fmt.Errorf(\"local state unreadable: %w\", err) }\nvar probe map[string]any\nif err := json.Unmarshal(data, &probe); err != nil {\n    return fmt.Errorf(\"local state corrupt: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := sMgr.RefreshState(); err != nil {\n    diags = diags.Append(fmt.Errorf(\"Failed to load the backend state file when preparing to update it: %s\", err))\n    // Attempt restore from backup if present.\n    if _, statErr := os.Stat(statePath + \".backup\"); statErr == nil {\n        diags = diags.Append(tfdiags.SimpleWarning(\"consider: cp terraform.tfstate.backup terraform.tfstate\"))\n    }\n    return diags\n}","preventionTips":["Keep terraform.tfstate.backup committed or mirrored to remote state.","Do not edit terraform.tfstate by hand or with external scripts.","Avoid concurrent terraform processes sharing one local state file.","Validate JSON before risky operations: `python -m json.tool terraform.tfstate`."],"tags":["terraform","state-migration","local-state","json","filesystem"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}