Tencent/WeKnora · error

failed to check bucket: %w

Error message

failed to check bucket: %w

What it means

After constructing the client, NewS3FileService calls svc.bucketExists to check whether the configured bucket is present. This error wraps a failure of that check itself (not 'bucket missing') — typically an API/transport failure like bad credentials, wrong region, or unreachable endpoint.

Source

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

		bucketName: bucketName,
		pathPrefix: pathPrefix,
	}, nil
}

// 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
	}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check the wrapped error for the S3 API code (AccessDenied, PermanentRedirect, etc.)
2. Ensure the configured region matches the bucket's actual region
3. Verify credentials are valid and not expired at service startup
4. Confirm network/DNS reachability of the endpoint (curl the endpoint health path)

Example fix

// before
exists, err := svc.bucketExists(context.Background())
if err != nil { return nil, fmt.Errorf("failed to check bucket: %w", err) }
// after
exists, err := svc.bucketExists(context.Background())
if err != nil {
    return nil, fmt.Errorf("failed to check bucket: %w", err) // inspect %w: usually region or credential issue
}

// connectivity pre-check before full service init
if err := CheckS3ConnectivityWithOptions(opts); err != nil { return err }

svc, err := NewS3FileService(...)
if err != nil && strings.Contains(err.Error(), "failed to check bucket") {
    // retry with backoff; check region/credentials before giving up
    time.Sleep(2 * time.Second)
    svc, err = NewS3FileService(...)
}

When it happens

Trigger: bucketExists' HeadBucket/API call fails due to invalid credentials, region mismatch with the bucket, DNS/network failure to the endpoint, or blocked ports/firewalls when NewS3FileService is invoked by initRawFileService at startup.

Common situations: Endpoint reachable but region wrong (301/AuthorizationHeaderMalformed), STS-credentialed setups where tokens are expired at boot, MinIO behind a proxy that strips required headers, offline dev environments.

Related errors

• failed to check bucket: %w
• failed to upload file to OBS: %w
• failed to get file from OBS: %w
• failed to copy file in OBS: %w
• failed to get file from S3: %w

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