Tencent/WeKnora · error

failed to create bucket: %w

Error message

failed to create bucket: %w

What it means

S3 service constructor: the configured bucket was reported missing and createBucket failed while attempting to create it (permissions, region constraints, or name conflict), so the file service cannot initialize and construction aborts.

Source

Thrown at internal/application/service/file/s3.go:113

// NewS3FileService creates an AWS S3 file service.
// It verifies that the bucket exists and creates it if missing.
func NewS3FileService(endpoint,
	accessKey, secretKey, bucketName, region, pathPrefix string,
) (interfaces.FileService, error) {
	svc, err := newS3Client(endpoint, accessKey, secretKey, bucketName, region, pathPrefix, false)
	if err != nil {
		return nil, err
	}

	// Check if bucket exists
	exists, err := svc.bucketExists(context.Background())
	if err != nil {
		return nil, fmt.Errorf("failed to check bucket: %w", err)
	}

	if !exists {
		if err = svc.createBucket(context.Background()); err != nil {
			return nil, fmt.Errorf("failed to create bucket: %w", err)
		}
	}

	return svc, nil
}

// NewS3FileServiceWithOptions is the instance-aware S3 constructor. Existing
// callers keep the historical endpoint-based path-style inference.
func NewS3FileServiceWithOptions(endpoint, accessKey, secretKey, bucketName, region, pathPrefix string, forcePathStyle bool) (interfaces.FileService, error) {
	svc, err := newS3Client(endpoint, accessKey, secretKey, bucketName, region, pathPrefix, forcePathStyle)
	if err != nil {
		return nil, err
	}
	exists, err := svc.bucketExists(context.Background())
	if err != nil {
		return nil, fmt.Errorf("failed to check bucket: %w", err)
	}
	if !exists {

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check S3 credentials have CreateBucket permission
2. Pre-create the bucket with correct region settings
3. Inspect the wrapped AWS error for the specific denial

When it happens

Trigger: Thrown at internal/application/service/file/s3.go:113 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/85b79f7108f03b38. Report an issue: GitHub.