hashicorp/terraform · error

error retrieving state

Error message

error retrieving state: %v

What it means

Thrown in getStatePayload when s.tfeClient.StateVersions.ReadCurrent fails for any reason other than tfe.ErrResourceNotFound (which is treated as an empty/new workspace and returns nil). This is the API call that fetches the current state version metadata for the workspace before downloading the actual state bytes. The %v (not %w) embeds the raw TFE client error string.

Solutions

1. Verify the API token is valid and the authenticated identity has read access to the workspace
2. Check network connectivity and retry if the error is a transient HTTP failure
3. Confirm the workspace still exists in the specified organization
4. Inspect the wrapped error text for HTTP status codes (401/403 = auth, 5xx = server, 429 = rate limit)

// Before RefreshState, verify connectivity and auth:
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if _, err := tfeClient.Organizations.Read(ctx, organization); err != nil {
    return fmt.Errorf("cannot reach TFE org %s, state refresh will fail: %w", organization, err)
}

// Retry RefreshState for transient retrieval failures:
backoff := time.Second
for attempt := 0; attempt < 5; attempt++ {
    err := stateMgr.RefreshState()
    if err == nil {
        break
    }
    if isRetryableHTTPError(err) {
        time.Sleep(backoff)
        backoff *= 2
        continue
    }
    return err // auth/permission errors are not retryable
}

When it happens

Trigger: Expired or invalid API token causing 401/403; network failure reaching the TFE endpoint; TFE 5xx server error; workspace deleted between the backend config read and the state read; user lacks read permission on the workspace; rate limiting (429) exhausted retries.

Common situations: Rotated API token not yet propagated; intermittent connectivity from CI runners to app.terraform.io; workspace permission changed by an admin removing the CI service account; TFE instance restarting or under maintenance.

Related errors

• error downloading state
• error uploading state
• could not read state version output
• could not read state version outputs
• Error downloading state

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

Appendix: source

Thrown at internal/cloud/state.go:417

	s.readSerial = stateFile.Serial
	s.readState = s.state.DeepCopy()
	return nil
}

func (s *State) getStatePayload() (*remote.Payload, error) {
	ctx := context.Background()

	// Check the x-terraform-snapshot-interval header to see if it has a non-empty
	// value which would indicate snapshots are enabled
	ctx = tfe.ContextWithResponseHeaderHook(ctx, s.readSnapshotIntervalHeader)

	sv, err := s.tfeClient.StateVersions.ReadCurrent(ctx, s.workspace.ID)
	if err != nil {
		if err == tfe.ErrResourceNotFound {
			// If no state exists, then return nil.
			return nil, nil
		}
		return nil, fmt.Errorf("error retrieving state: %v", err)
	}

	state, err := s.tfeClient.StateVersions.Download(ctx, sv.DownloadURL)
	if err != nil {
		return nil, fmt.Errorf("error downloading state: %v", err)
	}

	// If the state is empty, then return nil.
	if len(state) == 0 {
		return nil, nil
	}

	// Get the MD5 checksum of the state.
	sum := md5.Sum(state)

	return &remote.Payload{
		Data: state,
		MD5:  sum[:],

View on GitHub (pinned to d32a084675)