Failed to load the backend state file when preparing to upda

Error message

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

What it means

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.

Source

Thrown at internal/command/state_migrate.go:428

	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 c9def3e214)

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.

Example fix

# before: local state file corrupted mid-migration
ls .terraform/terraform.tfstate
# (missing or invalid)

# after: restore backup, retry
cp .terraform/terraform.tfstate.backup .terraform/terraform.tfstate
terraform state migrate

Defensive patterns

Strategy: validation

Validate before calling

// before the post-migration update, sanity-check the local state file.
func stateFileReadable(path string) error {
    f, err := os.Open(path)
    if err != nil { return err }
    defer f.Close()
    return nil
}

Prevention

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.

When it happens

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

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

Related errors

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