Failed to load the backend state file when preparing to…

Error message

Failed to load the backend state file when preparing to update it: %s

What it means

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.

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.

Example fix

# before
 terraform state migrate  # local state corrupt

# after
 cp terraform.tfstate.backup terraform.tfstate
 terraform state migrate

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check the local state file is readable + valid JSON.
data, err := os.ReadFile(statePath)
if err != nil { return fmt.Errorf("local state unreadable: %w", err) }
var probe map[string]any
if err := json.Unmarshal(data, &probe); err != nil {
    return fmt.Errorf("local state corrupt: %w", err)
}

Try / catch

if err := sMgr.RefreshState(); err != nil {
    diags = diags.Append(fmt.Errorf("Failed to load the backend state file when preparing to update it: %s", err))
    // Attempt restore from backup if present.
    if _, statErr := os.Stat(statePath + ".backup"); statErr == nil {
        diags = diags.Append(tfdiags.SimpleWarning("consider: cp terraform.tfstate.backup terraform.tfstate"))
    }
    return diags
}

Prevention

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`.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/1bf3ec3040166b5d. Report an issue: GitHub.

Appendix: source

Thrown at internal/command/state_migrate.go:435

	return strings.TrimSpace(helpText)
}

func (c *StateMigrateCommand) Synopsis() string {
	return "Migrate the state from one location to another"
}

const (
	MigrationSource      = "source"
	MigrationDestination = "destination"
)

func (c *StateMigrateCommand) updateBackendStateFile(s *workdir.BackendStateFile) tfdiags.Diagnostics {
	var diags tfdiags.Diagnostics

	statePath := filepath.Join(c.DataDir(), DefaultStateFilename)
	sMgr := &clistate.LocalState{Path: statePath}
	if err := sMgr.RefreshState(); err != nil {
		diags = diags.Append(fmt.Errorf("Failed to load the backend state file when preparing to update it: %s", err))
		return diags
	}

	if err := sMgr.WriteState(s); err != nil {
		diags = diags.Append(errBackendWriteSavedDiag(err))
		return diags
	}
	if err := sMgr.PersistState(); err != nil {
		diags = diags.Append(errBackendWriteSavedDiag(err))
		return diags
	}

	return diags
}

func (c *StateMigrateCommand) getDestinationStateStoreProviderRequirements(provider addrs.Provider, configReqs *configs.RequiredProviders) (providerreqs.Requirements, tfdiags.Diagnostics) {
	var diags tfdiags.Diagnostics
	req := make(providerreqs.Requirements, 1)

View on GitHub (pinned to d32a084675)