{"record":{"id":"5da3802fa9f74593","repo":"hashicorp/terraform","slug":"unable-to-list-objects-in-s3-bucket-q-with-prefix","errorCode":null,"errorMessage":"Unable to list objects in S3 bucket %q with prefix %q: %w","messagePattern":"Unable to list objects in S3 bucket %q with prefix %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote-state/s3/backend_state.go","lineNumber":78,"sourceCode":"\t}\n\n\twss := []string{backend.DefaultStateName}\n\n\tctx, baselog := baselogging.NewHcLogger(ctx, log)\n\tctx = baselogging.RegisterLogger(ctx, baselog)\n\n\tpages := s3.NewListObjectsV2Paginator(b.s3Client, params)\n\tfor pages.HasMorePages() {\n\t\tpage, err := pages.NextPage(ctx)\n\t\tif err != nil {\n\t\t\tif IsA[*s3types.NoSuchBucket](err) {\n\t\t\t\treturn nil, diags.Append(fmt.Errorf(errS3NoSuchBucket, b.bucketName, err))\n\t\t\t}\n\t\t\tif foo, ok := As[smithy.APIError](err); b.workspaceKeyPrefix == defaultWorkspaceKeyPrefix && ok && foo.ErrorCode() == \"AccessDenied\" {\n\t\t\t\tlog.Warn(\"Unable to list non-default workspaces\", \"err\", err.Error())\n\t\t\t\treturn wss[:1], nil\n\t\t\t}\n\t\t\treturn nil, diags.Append(fmt.Errorf(\"Unable to list objects in S3 bucket %q with prefix %q: %w\", b.bucketName, prefix, err))\n\t\t}\n\n\t\tfor _, obj := range page.Contents {\n\t\t\tws := b.keyEnv(aws.ToString(obj.Key))\n\t\t\tif ws != \"\" {\n\t\t\t\twss = append(wss, ws)\n\t\t\t}\n\t\t}\n\t}\n\n\tsort.Strings(wss[1:])\n\treturn wss, diags\n}\n\nfunc (b *Backend) keyEnv(key string) string {\n\tprefix := b.workspaceKeyPrefix\n\n\tif prefix == \"\" {","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/backend/remote-state/s3/backend_state.go#L60-L96","documentation":"Thrown by Backend.Workspaces in the S3 backend when ListObjectsV2 NextPage errors and the error is neither NoSuchBucket nor (in the default-prefix case) an AccessDenied smithy.APIError. It is the catch-all list failure wrapping the underlying error with %w so callers can errors.Is/As it. The state listing operation cannot proceed.","triggerScenarios":"pages.NextPage(ctx) errors, IsA[*s3types.NoSuchBucket] is false, and either the prefix is non-default or the error is not a smithy AccessDenied. Causes: throttling (SlowDown), transient 5xx, iam ListBucket permission missing, KMS decrypt issue on listing, or STS token expired mid-list.","commonSituations":"Throttling on a hot bucket; expired STS session token; custom workspace_key_prefix with s3:ListBucket scoped to a different prefix; KMS key disabled; region partition mismatch.","solutions":["Inspect the wrapped error (%w) for `SlowDown`/`Throttling` and retry with backoff.","Grant the principal `s3:ListBucket` on the bucket scoped to the workspace key prefix.","Refresh STS credentials (re-assume role) if the session expired.","Verify KMS key used for bucket is enabled and accessible."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// preflight: assert ListBucket permission with a scoped call\n_, err := s3Client.ListObjectsV2(ctx, &s3.ListObjectsV2Input{Bucket: aws.String(b), MaxKeys: aws.Int32(1)})\nif err != nil { return fmt.Errorf(\"cannot list bucket %s: %w\", b, err) }","typeGuard":"func isAccessDeniedOrThrottle(err error) bool {\n    var ae smithy.APIError\n    if errors.As(err, &ae) {\n        return ae.ErrorCode()==\"AccessDenied\" || ae.ErrorCode()==\"SlowDown\" || ae.ErrorCode()==\"Throttling\"\n    }\n    return false\n}","tryCatchPattern":"page, err := pages.NextPage(ctx)\nif err != nil {\n    var ae smithy.APIError\n    if errors.As(err, &ae) && (ae.ErrorCode()==\"SlowDown\"||ae.ErrorCode()==\"Throttling\") { backoff(); continue }\n    return err\n}","preventionTips":["Grant s3:ListBucket scoped to the workspace key prefix.","Refresh STS credentials before long lists.","Add request-exponential-backoff for S3 list throttling."],"tags":["s3","aws","list-objects","throttling","permissions"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}