{"record":{"id":"5d25a43580e57a88","repo":"Tencent/WeKnora","slug":"failed-to-check-bucket-w-5d25a4","errorCode":null,"errorMessage":"failed to check bucket: %w","messagePattern":"failed to check bucket: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/application/service/file/s3.go","lineNumber":108,"sourceCode":"\t\tbucketName: bucketName,\n\t\tpathPrefix: pathPrefix,\n\t}, nil\n}\n\n// NewS3FileService creates an AWS S3 file service.\n// It verifies that the bucket exists and creates it if missing.\nfunc NewS3FileService(endpoint,\n\taccessKey, secretKey, bucketName, region, pathPrefix string,\n) (interfaces.FileService, error) {\n\tsvc, err := newS3Client(endpoint, accessKey, secretKey, bucketName, region, pathPrefix, false)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\t// Check if bucket exists\n\texists, err := svc.bucketExists(context.Background())\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to check bucket: %w\", err)\n\t}\n\n\tif !exists {\n\t\tif err = svc.createBucket(context.Background()); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to create bucket: %w\", err)\n\t\t}\n\t}\n\n\treturn svc, nil\n}\n\n// NewS3FileServiceWithOptions is the instance-aware S3 constructor. Existing\n// callers keep the historical endpoint-based path-style inference.\nfunc NewS3FileServiceWithOptions(endpoint, accessKey, secretKey, bucketName, region, pathPrefix string, forcePathStyle bool) (interfaces.FileService, error) {\n\tsvc, err := newS3Client(endpoint, accessKey, secretKey, bucketName, region, pathPrefix, forcePathStyle)\n\tif err != nil {\n\t\treturn nil, err\n\t}","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/application/service/file/s3.go#L90-L126","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the wrapped error for the S3 API code (AccessDenied, PermanentRedirect, etc.)","Ensure the configured region matches the bucket's actual region","Verify credentials are valid and not expired at service startup","Confirm network/DNS reachability of the endpoint (curl the endpoint health path)"],"exampleFix":"// before\nexists, err := svc.bucketExists(context.Background())\nif err != nil { return nil, fmt.Errorf(\"failed to check bucket: %w\", err) }\n// after\nexists, err := svc.bucketExists(context.Background())\nif err != nil {\n    return nil, fmt.Errorf(\"failed to check bucket: %w\", err) // inspect %w: usually region or credential issue\n}","handlingStrategy":"retry","validationCode":"// connectivity pre-check before full service init\nif err := CheckS3ConnectivityWithOptions(opts); err != nil { return err }","typeGuard":null,"tryCatchPattern":"svc, err := NewS3FileService(...)\nif err != nil && strings.Contains(err.Error(), \"failed to check bucket\") {\n    // retry with backoff; check region/credentials before giving up\n    time.Sleep(2 * time.Second)\n    svc, err = NewS3FileService(...)\n}","preventionTips":["Match the configured region to the bucket's region","Verify credentials validity at startup (aws sts get-caller-identity equivalent)","Add retry/backoff around startup bucket checks","Monitor endpoint reachability from the deployment network"],"tags":["s3","bucket","network","startup"],"backgroundTag":"bucket-check-failed","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}