hashicorp/terraform · error

Error retrieving state

Error message

Error retrieving state: %v

What it means

remoteClient.Get reads the current state version for the workspace via StateVersions.ReadCurrent. ErrResourceNotFound is treated as 'no state yet' and returns nil; every other failure (auth, permissions, API 5xx, network) becomes this error. This runs during RefreshState before plan/apply/pull.

Solutions

1. Verify the token has 'Read State' (or higher) permission on the workspace.
2. Re-run `terraform init` to refresh cached workspace metadata if the workspace was recreated.
3. Retry on transient 5xx/network errors after confirming TFC status.
4. If self-hosted TFE, check that the workspace still exists and the state backend (e.g. S3) is healthy.

// Pre-flight read-state check
_, err := c.StateVersions.ReadCurrent(ctx, wsID)
if err != nil && err != tfe.ErrResourceNotFound { return err }

// Retry non-NotFound errors from ReadCurrent
err := retryOnHTTP(3, func() error {
    e := c.StateVersions.ReadCurrent(ctx, wsID)
    if e == tfe.ErrResourceNotFound { return nil }
    return e
})

When it happens

Trigger: StateVersions.ReadCurrent(ctx, workspace.ID) fails with a non-NotFound error: 401/403 (token can't read state versions in this workspace), 404 on the workspace itself after ID was cached, 5xx, or transport error.

Common situations: Token downgraded to a team without 'Read State' access; workspace recreated with a new ID while the backend held the old one; TFC state backend degraded; network blip during `terraform init`/`plan`.

Related errors

• Error downloading state
• error deleting workspace
• error loading variables
• error loading workspace
• error uploading state

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

Appendix: source

Thrown at internal/backend/remote/backend_state.go:62

func (e errorUnlockFailed) Error() string {
	return e.innerError.Error()
}

var _ Fatal = errorUnlockFailed{}

// Get the remote state.
func (r *remoteClient) Get() (*remote.Payload, tfdiags.Diagnostics) {
	var diags tfdiags.Diagnostics
	ctx := context.Background()

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

	state, err := r.client.StateVersions.Download(ctx, sv.DownloadURL)
	if err != nil {
		return nil, diags.Append(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)