hashicorp/terraform · error

failed to create bucket %v: %v

Error message

failed to create bucket %v: %v

What it means

Raised by putBucket() when cosClient.Bucket.Put returns a nil response — the create-bucket request never produced a response. The wrapped error is the transport failure. This is the no-response branch of bucket creation.

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 c9def3e214)

Solutions

1. Verify the configured region/endpoint is reachable and the region string is valid for Tencent COS.
2. Confirm credentials are valid and authorised to create buckets.
3. Retry after confirming connectivity.
4. If the bucket already exists in another region, point the backend at the correct region rather than relying on auto-create.

Example fix

# validate region + reachability
curl -I https://cos.ap-guangzhou.myqcloud.com
# then re-init
terraform init

// Preflight: confirm endpoint reachability and a valid region string.
var validCOSRegions = map[string]bool{"ap-guangzhou":true,"ap-beijing":true /*...*/}
func validRegion(r string) bool { return validCOSRegions[r] }

if err := c.putBucket(); err != nil {
    if strings.Contains(err.Error(), "failed to create bucket") {
        // nil-response: check connectivity/region then retry
    }
}

When it happens

Trigger: At client.go:305-308: rsp == nil. Triggered when creating the bucket during backend init: network/DNS/TLS failure, invalid endpoint, or auth failure before a response. Note a 409 (already exists) is silently accepted at client.go:313.

Common situations: Backend configured with 'create_bucket=true' but the endpoint/region is wrong or unreachable; credentials invalid causing auth to fail before response; network outage during 'terraform init'.

Related errors

• bucket %s not exists
• failed to delete bucket %v: %v
• failed to save file to %v: %v
• failed to delete file %v: %v
• failed to empty bucket %v: %v

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