hashicorp/terraform · error

S3 bucket does not exist. The referenced S3 bucket must…

Error message

S3 bucket %q does not exist.

The referenced S3 bucket must have been previously created. If the S3 bucket
was created within the last minute, please wait for a minute or two and try
again.

Error: %s

What it means

Thrown by RemoteClient.Get in the S3 backend when HeadObject errors and the error type-asserts to *s3types.NoSuchBucket. Same errS3NoSuchBucket template as 371, but raised during state read rather than workspace listing: the bucket that holds the state object does not exist (or is not visible to the caller's credentials).

Solutions

1. Verify with `aws s3api head-bucket --bucket <name> --region <region>` using the same profile.
2. Check the backend `bucket` and `region` for typos.
3. Confirm the assumed role / profile is in the account that owns the bucket.

// preflight: head the bucket with the same credentials tofu uses
_, err := s3Client.HeadBucket(ctx, &s3.HeadBucketInput{Bucket: aws.String(c.bucketName)})
if err != nil { return fmt.Errorf("bucket %s not visible with current creds/region: %w", c.bucketName, err) }

func isNoSuchBucketErr(err error) bool {
    var nsb *s3types.NoSuchBucket
    return errors.As(err, &nsb)
}

When it happens

Trigger: c.s3Client.HeadObject(ctx, headInput) errors and IsA[*s3types.NoSuchBucket] matches. The bucket c.bucketName does not exist for the caller's account/region/credentials. Distinct from NotFound (which means the bucket exists but the key does not).

Common situations: Bucket deleted out-of-band; wrong `bucket` value in backend config; assumed a role in the wrong account; region mismatch; bucket in a different partition (aws-cn vs aws).

Related errors

• S3 bucket does not exist. The referenced S3 bucket must…
• Unable to access object
• can't delete default state
• Error unlocking S3 state. Lock ID
• failed to lock s3 state

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

Appendix: source

Thrown at internal/backend/remote-state/s3/client.go:142

	return payload, diags.Append(err)
}

func (c *RemoteClient) get(ctx context.Context) (*remote.Payload, error) {
	headInput := &s3.HeadObjectInput{
		Bucket: aws.String(c.bucketName),
		Key:    aws.String(c.path),
	}
	if c.serverSideEncryption && c.customerEncryptionKey != nil {
		headInput.SSECustomerKey = aws.String(base64.StdEncoding.EncodeToString(c.customerEncryptionKey))
		headInput.SSECustomerAlgorithm = aws.String(s3EncryptionAlgorithm)
		headInput.SSECustomerKeyMD5 = aws.String(c.getSSECustomerKeyMD5())
	}

	headOut, err := c.s3Client.HeadObject(ctx, headInput)
	if err != nil {
		switch {
		case IsA[*s3types.NoSuchBucket](err):
			return nil, fmt.Errorf(errS3NoSuchBucket, c.bucketName, err)
		case IsA[*s3types.NotFound](err):
			return nil, nil
		}
		return nil, fmt.Errorf("Unable to access object %q in S3 bucket %q: %w", c.path, c.bucketName, err)
	}

	// Pre-allocate the full buffer to avoid re-allocations and GC
	buf := make([]byte, int(aws.ToInt64(headOut.ContentLength)))
	w := manager.NewWriteAtBuffer(buf)

	downloadInput := &s3.GetObjectInput{
		Bucket: aws.String(c.bucketName),
		Key:    aws.String(c.path),
	}
	if c.serverSideEncryption && c.customerEncryptionKey != nil {
		downloadInput.SSECustomerKey = aws.String(base64.StdEncoding.EncodeToString(c.customerEncryptionKey))
		downloadInput.SSECustomerAlgorithm = aws.String(s3EncryptionAlgorithm)
		downloadInput.SSECustomerKeyMD5 = aws.String(c.getSSECustomerKeyMD5())

View on GitHub (pinned to d32a084675)