{"record":{"id":"05eb8275bcf50e37","repo":"hashicorp/terraform","slug":"querying-cloud-storage-failed-v","errorCode":null,"errorMessage":"querying Cloud Storage failed: %v","messagePattern":"querying Cloud Storage failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote-state/gcs/backend_state.go","lineNumber":47,"sourceCode":"// state is always returned as the first element in the slice.\nfunc (b *Backend) Workspaces() ([]string, tfdiags.Diagnostics) {\n\tvar diags tfdiags.Diagnostics\n\tctx := context.TODO()\n\n\tstates := []string{backend.DefaultStateName}\n\n\tbucket := b.storageClient.Bucket(b.bucketName)\n\tobjs := bucket.Objects(ctx, &storage.Query{\n\t\tDelimiter: \"/\",\n\t\tPrefix:    b.prefix,\n\t})\n\tfor {\n\t\tattrs, err := objs.Next()\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif err != nil {\n\t\t\treturn nil, diags.Append(fmt.Errorf(\"querying Cloud Storage failed: %v\", err))\n\t\t}\n\n\t\tname := path.Base(attrs.Name)\n\t\tif !strings.HasSuffix(name, stateFileSuffix) {\n\t\t\tcontinue\n\t\t}\n\t\tst := strings.TrimSuffix(name, stateFileSuffix)\n\n\t\tif st != backend.DefaultStateName {\n\t\t\tstates = append(states, st)\n\t\t}\n\t}\n\n\tsort.Strings(states[1:])\n\treturn states, diags\n}\n\n// DeleteWorkspace deletes the named workspaces. The \"default\" state cannot be deleted.","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/backend/remote-state/gcs/backend_state.go#L29-L65","documentation":"Thrown while listing state objects in the bucket during Workspaces. The backend paginates bucket.Objects with a Delimiter+Prefix query; any non-iterator.Done error from objs.Next is wrapped here.","triggerScenarios":"bucket.Objects iteration returns a non-Done error — insufficient IAM permission (storage.objects.list) on the bucket, bucket does not exist, network/transport error, or request quota exceeded.","commonSituations":"Service account has storage.objectAdmin but is missing the list permission for the chosen prefix; the configured bucket was renamed or deleted; transient 429/5xx from GCS; wrong project credential scoped to a different bucket.","solutions":["Grant the service account storage.objects.list (and get) on the bucket, e.g. roles/storage.objectAdmin or roles/storage.objectViewer.","Confirm the bucket name in the backend block matches an existing bucket.","Inspect the wrapped %v error to distinguish permission vs. existence vs. quota.","Retry transient failures after verifying IAM propagation."],"exampleFix":"// before — service account lacks list permission\n// after\ngsutil iam ch serviceAccount:terraform@proj.iam.gserviceaccount.com:roles/storage.objectViewer gs://tf-state","handlingStrategy":"validation","validationCode":"// Pre-flight: verify bucket is listable before running terraform.\n// gsutil ls gs://<bucket>/<prefix> should return successfully.","typeGuard":null,"tryCatchPattern":"// Distinguish permission errors from transient ones.\nfor {\n    attrs, err := objs.Next()\n    if err == iterator.Done { break }\n    if err != nil {\n        if isTransient(err) { continue } // or backoff\n        return fmt.Errorf(\"querying Cloud Storage failed: %w\", err)\n    }\n    _ = attrs\n}","preventionTips":["Grant roles/storage.objectViewer (or objectAdmin) on the bucket.","Run a pre-flight `gsutil ls gs://bucket/prefix` in CI.","Treat wrapped errors of 429/5xx as retryable."],"tags":["gcs","backend","storage","iam","permissions","workspaces"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}