Tencent/WeKnora · error

failed to create OSS bucket: %w

Error message

failed to create OSS bucket: %w

What it means

OSS bucket bootstrap: the bucket was reported missing and PutBucket creation failed with a non-409 error (permissions, quota, or invalid name), so the bucket cannot be ensured and service construction aborts.

Source

Thrown at internal/application/service/file/oss.go:69

// ossEnsureBucket checks if the bucket exists and creates it if missing.
func ossEnsureBucket(client *oss.Client, bucketName string) error {
	exists, err := client.IsBucketExist(context.Background(), bucketName)
	if err != nil {
		return fmt.Errorf("failed to check OSS bucket: %w", err)
	}
	if exists {
		return nil
	}

	_, err = client.PutBucket(context.Background(), &oss.PutBucketRequest{
		Bucket: oss.Ptr(bucketName),
	})
	if err != nil {
		var svcErr *oss.ServiceError
		if errors.As(err, &svcErr) && svcErr.StatusCode == http.StatusConflict {
			return nil
		}
		return fmt.Errorf("failed to create OSS bucket: %w", err)
	}
	return nil
}

// NewOssFileService creates an Aliyun OSS file service.
// It verifies that the bucket exists and creates it if missing.
func NewOssFileService(endpoint, region, accessKey, secretKey, bucketName, pathPrefix string) (interfaces.FileService, error) {
	return NewOssFileServiceWithTempBucket(endpoint, region, accessKey, secretKey, bucketName, pathPrefix, "", "")
}

// NewOssFileServiceWithTempBucket creates an Aliyun OSS file service with optional temp bucket.
func NewOssFileServiceWithTempBucket(endpoint, region, accessKey, secretKey, bucketName, pathPrefix, tempBucketName, tempRegion string) (interfaces.FileService, error) {
	client, err := newOSSClient(endpoint, region, accessKey, secretKey)
	if err != nil {
		return nil, err
	}

	if err := ossEnsureBucket(client, bucketName); err != nil {

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check credentials have bucket-creation permission
2. Pre-create the bucket manually
3. Inspect the wrapped ServiceError for the exact OSS denial

When it happens

Trigger: Thrown at internal/application/service/file/oss.go:69 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/0b736b52210f150b. Report an issue: GitHub.