Tencent/WeKnora · critical

bucket %q does not exist

Error message

bucket %q does not exist

What it means

CheckConnectivity confirms the configured bucket exists via IsBucketExist; this error is returned when the OSS service responds successfully but reports that the bucket configured for this service (s.bucketName) does not exist. It is a definitive configuration/deployment problem, not a transient failure.

Source

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

	rest := strings.TrimPrefix(filePath, ossScheme)
	parts := strings.SplitN(rest, "/", 2)
	if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
		return "", "", fmt.Errorf("invalid OSS file path: %s", filePath)
	}
	return parts[0], parts[1], nil
}

// CheckConnectivity verifies OSS is reachable and the main bucket exists.
func (s *ossFileService) CheckConnectivity(ctx context.Context) error {
	checkCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
	defer cancel()

	exists, err := s.client.IsBucketExist(checkCtx, s.bucketName)
	if err != nil {
		return fmt.Errorf("failed to check OSS bucket: %w", err)
	}
	if !exists {
		return fmt.Errorf("bucket %q does not exist", s.bucketName)
	}
	return nil
}

// SaveFile saves a file to OSS using the Uploader manager for large files.
func (s *ossFileService) SaveFile(ctx context.Context,
	file *multipart.FileHeader, tenantID uint64, knowledgeID string,
) (string, error) {
	ext := filepath.Ext(file.Filename)
	objectName := fmt.Sprintf("%s%d/%s/%s%s", s.pathPrefix, tenantID, knowledgeID, uuid.New().String(), ext)

	src, err := file.Open()
	if err != nil {
		return "", fmt.Errorf("failed to open file: %w", err)
	}
	defer src.Close()

	contentType := file.Header.Get("Content-Type")

View on GitHub (pinned to 988cbb0330)

Solutions

1. Create the missing bucket (via OSS console, ossutil mb oss://<bucket>, or IaC)
2. Verify the bucket name in service config matches an existing bucket and the endpoint/region matches the bucket's region
3. Confirm credentials belong to the account that owns (or has rights to) the bucket
4. Check for typos or stale environment variables (e.g. pointing at a dev bucket name in prod)

Example fix

// before (config)
OSS_BUCKET=my-app-files   // bucket never created
// after
$ ossutil mb oss://my-app-files --region cn-hangzhou
OSS_BUCKET=my-app-files

// Before starting the service, verify the bucket exists using the OSS SDK directly
client, _ := oss.New(endpoint, ak, sk)
exists, err := client.IsBucketExist(ctx, cfg.Bucket)
if err != nil { return err }
if !exists { return fmt.Errorf("bucket %q missing; run: ossutil mb oss://%s", cfg.Bucket, cfg.Bucket) }

if err := svc.CheckConnectivity(ctx); err != nil {
    if strings.Contains(err.Error(), "does not exist") {
        log.Fatalf("fatal config error: create bucket %q first", cfg.Bucket) // not retryable
    }
    return err
}

When it happens

Trigger: Calling CheckConnectivity when the bucket name in configuration was never created, was deleted, is misspelled, or belongs to another account/region (bucket names are global per region).

Common situations: Fresh environment where infra-as-code hasn't created the bucket; typo in BUCKET_NAME config; bucket created in a different region than the endpoint used; bucket deleted or renamed; wrong account credentials that can't see the bucket.

Related errors

• custom agent configuration is required for agent QA
• summary model (model_id) is not configured in custom agent s
• rerank model is not configured: please set rerank_model_id o
• JWKS document contains no keys
• cannot verify OIDC id_token: issuer is not configured

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