{"record":{"id":"2e83cebad7c04037","repo":"hashicorp/terraform","slug":"error-downloading-state-v-2e83ce","errorCode":null,"errorMessage":"error downloading state: %v","messagePattern":"error downloading state: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cloud/state.go","lineNumber":422,"sourceCode":"func (s *State) getStatePayload() (*remote.Payload, error) {\n\tctx := context.Background()\n\n\t// Check the x-terraform-snapshot-interval header to see if it has a non-empty\n\t// value which would indicate snapshots are enabled\n\tctx = tfe.ContextWithResponseHeaderHook(ctx, s.readSnapshotIntervalHeader)\n\n\tsv, err := s.tfeClient.StateVersions.ReadCurrent(ctx, s.workspace.ID)\n\tif err != nil {\n\t\tif err == tfe.ErrResourceNotFound {\n\t\t\t// If no state exists, then return nil.\n\t\t\treturn nil, nil\n\t\t}\n\t\treturn nil, fmt.Errorf(\"error retrieving state: %v\", err)\n\t}\n\n\tstate, err := s.tfeClient.StateVersions.Download(ctx, sv.DownloadURL)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error downloading state: %v\", err)\n\t}\n\n\t// If the state is empty, then return nil.\n\tif len(state) == 0 {\n\t\treturn nil, nil\n\t}\n\n\t// Get the MD5 checksum of the state.\n\tsum := md5.Sum(state)\n\n\treturn &remote.Payload{\n\t\tData: state,\n\t\tMD5:  sum[:],\n\t}, nil\n}\n\ntype errorUnlockFailed struct {\n\tinnerError error","sourceCodeStart":404,"sourceCodeEnd":440,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/cloud/state.go#L404-L440","documentation":"After reading current-state-version metadata, Terraform downloads the actual state bytes from sv.DownloadURL via StateVersions.Download. This wraps any failure of that download: the (often expiring) download URL may be unreachable, expired, or the object-storage backend unavailable.","triggerScenarios":"getStatePayload succeeds at ReadCurrent but StateVersions.Download(url) fails: network egress blocked to the state-storage host, the presigned URL expired, or the object-storage endpoint returned an error.","commonSituations":"Restrictive egress proxies that permit the TFE API hostname but block the state-storage hostname, a large state over a flaky link, or an expired presigned URL after a long delay.","solutions":["Ensure network egress permits BOTH the HCP/TFE API host and the state storage host.","Retry immediately; a fresh download URL is issued each time.","Reduce state size (split workspaces) if downloads repeatedly time out.","Check proxy/TLS-interception settings that may break the download."],"exampleFix":"# before: egress firewall allows api host but blocks state storage host -> download fails\n# after: allow egress to the state storage hostname (e.g. S3 backend domain), then refresh\nterraform refresh","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := state.RefreshState(); err != nil {\n    if isTransientHTTP(err) || isDownloadError(err) {\n        // bounded retry; a fresh DownloadURL is issued each ReadCurrent\n    }\n}","preventionTips":["Allow egress to both the API host and the state-storage host","Retry immediately on expired presigned URLs","Keep state size manageable to avoid download timeouts"],"tags":["state-download","network","storage","retrieval"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T20:17:04.800Z"}