{"record":{"id":"bdfae04bd37c8eb9","repo":"hashicorp/terraform","slug":"failed-to-load-the-backend-state-file-s","errorCode":null,"errorMessage":"Failed to load the backend state file: %s","messagePattern":"Failed to load the backend state file: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/meta_backend.go","lineNumber":935,"sourceCode":"\t//\n\t// The remainder of this code often confusingly refers to this as a \"state\",\n\t// so it's unfortunately important to remember that this is not actually\n\t// what we _usually_ think of as \"state\", and is instead a local working\n\t// directory \"backend configuration state\" that is never persisted anywhere.\n\t//\n\t// Since the \"real\" state has since moved on to be represented by\n\t// states.State, we can recognize the special meaning of state that applies\n\t// to this function and its callees by their continued use of the\n\t// otherwise-obsolete terraform.State.\n\t// ------------------------------------------------------------------------\n\n\t// Get the path to where we store a local cache of backend configuration\n\t// if we're using a remote backend. This may not yet exist which means\n\t// we haven't used a non-local backend before. That is okay.\n\tstatePath := filepath.Join(m.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: %s\", err))\n\t\treturn nil, diags\n\t}\n\n\t// Load the state, it must be non-nil for the tests below but can be empty\n\ts := sMgr.State()\n\tif s == nil {\n\t\tlog.Printf(\"[TRACE] Meta.Backend: backend has not previously been initialized in this working directory\")\n\t\ts = workdir.NewBackendStateFile()\n\t} else if s.Backend != nil {\n\t\tlog.Printf(\"[TRACE] Meta.Backend: working directory was previously initialized for %q backend\", s.Backend.Type)\n\t} else if s.StateStore != nil {\n\t\tlog.Printf(\"[TRACE] Meta.Backend: working directory was previously initialized for %q state_store using provider %q, version %s\",\n\t\t\ts.StateStore.Type,\n\t\t\ts.StateStore.Provider.Source,\n\t\t\ts.StateStore.Provider.Version)\n\t} else {\n\t\tlog.Printf(\"[TRACE] Meta.Backend: working directory was previously initialized but has no backend (is using legacy remote state?)\")\n\t}","sourceCodeStart":917,"sourceCodeEnd":953,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/command/meta_backend.go#L917-L953","documentation":"Appended as a diagnostic in Meta.Backend() when RefreshState() on the local backend-state cache file (.terraform/terraform.tfstate) returns an error. This file stores the working directory's backend/state_store configuration snapshot — not the real infrastructure state. The %s wraps the clistate refresh error.","triggerScenarios":"sMgr.RefreshState() fails reading or parsing the file at DataDir()/DefaultStateFilename ('.terraform/terraform.tfstate'). Causes include a truncated/JSON-corrupt file, an I/O read error, or a permission denial on the file or its parent directory.","commonSituations":"A previous terraform process was killed mid-write leaving a half-written tfstate; an editor or sync tool (Dropbox/OneDrive) corrupted the file mid-sync; read permissions changed on .terraform/; restoring .terraform/ from a partial backup; a disk-full event during a prior write.","solutions":["Delete or move aside the corrupted .terraform/terraform.tfstate and re-run `terraform init` to regenerate it from config.","Check permissions/ownership on .terraform/ and its contents (chmod/chown).","Exclude .terraform/ from file-sync tools; store state/backend config only via the configured backend.","If the file is intentionally absent (fresh dir), ensure the directory exists and is writable."],"exampleFix":"# before: corrupted local backend state file\nterraform init\n# Failed to load the backend state file: ...\n# after\nrm .terraform/terraform.tfstate\nterraform init","handlingStrategy":"validation","validationCode":"// Validate the local backend-state file before running terraform\nstFile := filepath.Join(workdir, \".terraform\", \"terraform.tfstate\")\nif data, err := os.ReadFile(stFile); err == nil {\n    if !json.Valid(data) {\n        log.Fatalf(\"%s is corrupt (invalid JSON); remove and re-init\", stFile)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never hand-edit .terraform/terraform.tfstate; remove and re-init if corrupt.","Exclude .terraform/ from file-sync tools (Dropbox/OneDrive).","Ensure disk space and stable writes during terraform operations to avoid truncation."],"tags":["backend","filesystem","state-file","corruption","init"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T20:17:04.800Z"}