hashicorp/terraform · error

failed to create bucket

Error message

failed to create bucket %v: %v

What it means

Returned by putBucket() when the COS SDK returns a nil response pointer from Bucket.Put (create bucket). The create request never reached a state where COS could respond — a transport-level failure. The original SDK error is wrapped.

Solutions

1. Inspect the wrapped error and DEBUG line `putBucket <bucket>: error:`.
2. Verify credentials and region/endpoint configuration.
3. Test outbound connectivity to `cos.<region>.myqcloud.com` and `cos.<region>.tencentcloudapi.com`.
4. Retry once transport issues are resolved.

Example fix

// before: endpoint cannot be derived (missing region)
backend "cos" { bucket="new-tf-state-1250000000"; acl="private" }
// after: provide region
backend "cos" { bucket="new-tf-state-1250000000"; region="ap-guangzhou"; acl="private" }

// Validate connectivity + auth before attempting bucket creation
func canCreateBucket(ctx context.Context, client *cos.Client, bucket string) error {
    rsp, err := client.Bucket.Put(ctx, nil)
    if rsp == nil { return fmt.Errorf("transport failure creating bucket %s: %w", bucket, err) }
    defer rsp.Body.Close()
    if rsp.StatusCode == 409 { return nil } // already exists is fine
    if rsp.StatusCode >= 400 { return fmt.Errorf("create bucket failed: %d", rsp.StatusCode) }
    return nil
}

func isCreateBucketTransportFailure(rsp *cos.Response) bool { return rsp == nil }

// Retry nil-response bucket creates as transport errors
backoff.Retry(func() error {
    rsp, err := client.Bucket.Put(ctx, nil)
    if rsp == nil { return err }
    defer rsp.Body.Close()
    if rsp.StatusCode == 409 { return nil }
    if err != nil { return backoff.Permanent(err) }
    return nil
}, backoff.NewExponentialBackOff())

When it happens

Trigger: c.cosClient.Bucket.Put(...) returns (nil, err). Network failure, invalid endpoint, missing credentials, or context cancellation before any response.

Common situations: Backend configured without valid region/endpoint; expired SecretId/SecretKey; CI host without outbound access; the COS client URL was constructed incorrectly from the bucket/region.

Related errors

• failed to delete bucket
• bucket not exists
• failed to delete file
• failed to open file at
• failed to save file to

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

Appendix: source

Thrown at internal/backend/remote-state/cos/client.go:308

	log.Printf("[DEBUG] getBucket %s/%s: code: %d, error: %v", c.bucket, prefix, rsp.StatusCode, err)
	if rsp.StatusCode == 404 {
		err = fmt.Errorf("bucket %s not exists", c.bucket)
		return
	}

	if err != nil {
		return
	}

	return fs.Contents, nil
}

// putBucket create cos bucket
func (c *remoteClient) putBucket() error {
	rsp, err := c.cosClient.Bucket.Put(c.cosContext, nil)
	if rsp == nil {
		log.Printf("[DEBUG] putBucket %s: error: %v", c.bucket, err)
		return fmt.Errorf("failed to create bucket %v: %v", c.bucket, err)
	}
	defer rsp.Body.Close()

	log.Printf("[DEBUG] putBucket %s: code: %d, error: %v", c.bucket, rsp.StatusCode, err)
	if rsp.StatusCode == 409 {
		return nil
	}

	if err != nil {
		return fmt.Errorf("failed to create bucket %v: %v", c.bucket, err)
	}

	return nil
}

// deleteBucket delete cos bucket
func (c *remoteClient) deleteBucket(recursive bool) error {
	if recursive {

View on GitHub (pinned to d32a084675)