Tencent/WeKnora · error

failed to create TOS bucket: %w

Error message

failed to create TOS bucket: %w

What it means

TOS bucket bootstrap: HeadBucket returned 404 so a CreateBucketV2 was attempted, but 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/tos.go:141

	_, err := client.HeadBucket(context.Background(), &tos.HeadBucketInput{
		Bucket: bucketName,
	})
	if err == nil {
		return nil
	}

	var serverErr *tos.TosServerError
	if errors.As(err, &serverErr) && serverErr.StatusCode == 404 {
		_, createErr := client.CreateBucketV2(context.Background(), &tos.CreateBucketV2Input{
			Bucket: bucketName,
		})
		if createErr == nil {
			return nil
		}
		if errors.As(createErr, &serverErr) && serverErr.StatusCode == 409 {
			return nil
		}
		return fmt.Errorf("failed to create TOS bucket: %w", createErr)
	}

	return fmt.Errorf("failed to check TOS bucket: %w", err)
}

func joinTOSObjectKey(parts ...string) string {
	filtered := make([]string, 0, len(parts))
	for _, part := range parts {
		part = strings.Trim(part, "/")
		if part != "" {
			filtered = append(filtered, part)
		}
	}
	return strings.Join(filtered, "/")
}

func parseTOSFilePath(filePath string) (bucketName string, objectKey string, err error) {
	if !strings.HasPrefix(filePath, tosScheme) {

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check TOS credentials have bucket-creation permission
2. Pre-create the bucket manually
3. Inspect the wrapped create error for quota/naming limits

When it happens

Trigger: Thrown at internal/application/service/file/tos.go:141 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/e585f462746a0233. Report an issue: GitHub.