What causes "Failed to refresh state: %s " in hashicorp/terraform?

Retry — most remote-backend refresh errors are transient.

Failed to refresh state

Error message

Failed to refresh state: %s

What it means

Thrown by state_show.go when stateMgr.RefreshState() returns a non-nil error during `terraform state show`. StateMgr was constructed fine ([755] did not fire), but reading the latest snapshot from persistent storage failed. Mirror of [741] for the state show path.

Solutions

Retry — most remote-backend refresh errors are transient.
Confirm the state object exists in the backend (`aws s3 ls s3://<bucket>/<key>`).
Release a stale lock with `terraform force-unlock <LOCK_ID>` only if you are certain no run is active.
For local state, restore from terraform.tfstate.backup.

Example fix

# before: state object missing in S3
 terraform state show aws_instance.web

# after: restore object then retry
 aws s3 cp backup/terraform.tfstate s3://bucket/prod/terraform.tfstate
 terraform state show aws_instance.web

Defensive patterns

Strategy: retry

Validate before calling

// Head the state object before refresh (S3 example).
if _, err := s3Client.HeadObject(&s3.HeadObjectInput{Bucket: &bucket, Key: &key}); err != nil {
    return fmt.Errorf("state object missing: %w", err)
}

Try / catch

if err := stateMgr.RefreshState(); err != nil {
    if isTransientBackendErr(err) {
        // single retry; refresh is safe (read-only)
        if err2 := stateMgr.RefreshState(); err2 == nil { err = nil }
    }
    if err != nil {
        diags = diags.Append(fmt.Errorf("Failed to refresh state: %s\n", err))
        return view.DisplayResourceInstanceState(jsonformat.State{}, diags)
    }
}

Prevention

Enable versioning on the state bucket so deleted objects can be restored.
Never delete the state object out-of-band; use `terraform state` subcommands.
Use state locking and avoid `force-unlock` unless certain.
Schedule migrations during low-concurrency windows to avoid lock contention.

When it happens

Trigger: Backend is reachable but the GET/refresh of state fails: S3 NoSuchKey on the state object, HTTP backend 5xx, DynamoDB lock contention, corrupt local state file decode, network blip mid-read.

Common situations: State object deleted out-of-band but workspace metadata remains; transient provider error; concurrent run holds the lock; truncated state file from a prior interrupted apply; mismatched KMS/encryption key.

Related errors

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

Appendix: source

Thrown at internal/command/state_show.go:118

	schemas, diags := lr.Core.Schemas(lr.Config, lr.InputState)
	if diags.HasErrors() {
		return view.DisplayResourceInstanceState(jsonformat.State{}, diags)
	}

	// Get the state
	env, err := c.Workspace()
	if err != nil {
		diags = diags.Append(fmt.Sprintf("Error selecting workspace: %s\n", err))
		view.Diagnostics(diags)
		return 1
	}
	stateMgr, sDiags := b.StateMgr(env)
	if sDiags.HasErrors() {
		diags = diags.Append(fmt.Errorf(errStateLoadingState, sDiags.Err()))
		return view.DisplayResourceInstanceState(jsonformat.State{}, diags)
	}
	if err := stateMgr.RefreshState(); err != nil {
		diags = diags.Append(fmt.Errorf("Failed to refresh state: %s\n", err))
		return view.DisplayResourceInstanceState(jsonformat.State{}, diags)
	}

	state := stateMgr.State()
	if state == nil {
		diags = diags.Append(errors.New(errStateNotFound))
		return view.DisplayResourceInstanceState(jsonformat.State{}, diags)
	}

	is := state.ResourceInstance(addr)
	if !is.HasCurrent() {
		diags = diags.Append(errors.New(errNoInstanceFound))
		return view.DisplayResourceInstanceState(jsonformat.State{}, diags)
	}

	// check if the resource has a configured provider, otherwise this will use the default provider
	rs := state.Resource(addr.ContainingResource())
	absPc := addrs.AbsProviderConfig{

View on GitHub (pinned to d32a084675)