{"record":{"id":"23badb0455dc354d","repo":"flipped-aurora/gin-vue-admin","slug":"function-client-object-put-failed-err","errorCode":null,"errorMessage":"function client.Object.Put() failed, err:","messagePattern":"function client\\.Object\\.Put\\(\\) failed, err:","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/utils/upload/tencent_cos.go","lineNumber":34,"sourceCode":")\n\ntype TencentCOS struct{}\n\n// UploadFile upload file to COS\nfunc (*TencentCOS) UploadFile(ctx context.Context, file *multipart.FileHeader) (string, string, error) {\n\tclient := NewClient()\n\tf, openError := file.Open()\n\tif openError != nil {\n\t\tlogger.WithCtx(ctx).Mod(\"upload\").Err(openError).Error(\"function file.Open() failed\")\n\t\treturn \"\", \"\", errors.New(\"function file.Open() failed, err:\" + openError.Error())\n\t}\n\tdefer f.Close() // 创建文件 defer 关闭\n\tfileKey := fmt.Sprintf(\"%d%s\", time.Now().Unix(), file.Filename)\n\n\t_, err := client.Object.Put(context.Background(), global.GVA_CONFIG.TencentCOS.PathPrefix+\"/\"+fileKey, f, nil)\n\tif err != nil {\n\t\tlogger.WithCtx(ctx).Mod(\"upload\").Err(err).Error(\"function client.Object.Put() failed\")\n\t\treturn \"\", \"\", errors.New(\"function client.Object.Put() failed, err:\" + err.Error())\n\t}\n\treturn global.GVA_CONFIG.TencentCOS.BaseURL + \"/\" + global.GVA_CONFIG.TencentCOS.PathPrefix + \"/\" + fileKey, fileKey, nil\n}\n\n// DeleteFile delete file form COS\nfunc (*TencentCOS) DeleteFile(ctx context.Context, key string) error {\n\tclient := NewClient()\n\tname := global.GVA_CONFIG.TencentCOS.PathPrefix + \"/\" + key\n\t_, err := client.Object.Delete(context.Background(), name)\n\tif err != nil {\n\t\tlogger.WithCtx(ctx).Mod(\"upload\").Err(err).Error(\"function bucketManager.Delete() failed\")\n\t\treturn errors.New(\"function bucketManager.Delete() failed, err:\" + err.Error())\n\t}\n\treturn nil\n}\n\n// Exists 通过 Object.Head 检查对象是否存在；404 统一降级为 (false, nil)。\nfunc (*TencentCOS) Exists(ctx context.Context, key string) (bool, error) {","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/flipped-aurora/gin-vue-admin/blob/3136500ef380842b0eb6c4daa87c3f8a47fcf9e0/server/utils/upload/tencent_cos.go#L16-L52","documentation":"Wraps an error from the COS SDK's client.Object.Put() in TencentCOS.UploadFile(). Put() uploads the file stream to the bucket; any transport or COS-side rejection surfaces here.","triggerScenarios":"Calling UploadFile(ctx, file) when Object.Put fails: wrong SecretID/SecretKey, missing bucket or region config, path prefix issues, or network failure during transfer.","commonSituations":"Misconfigured GVA_CONFIG.TencentCOS (Bucket/Region/SecretID/SecretKey/PathPrefix), expired credentials, request body larger than limits, VPC without COS endpoint access.","solutions":["Check the wrapped err suffix for the COS error code (e.g. AccessDenied, SignatureDoesNotMatch)","Verify TencentCOS config keys in config.yaml: Bucket, Region, SecretID, SecretKey, BaseURL, PathPrefix","Confirm outbound network access to the COS regional endpoint","Retry transient 5xx/timeout errors; check COS console for bucket ACL/cors restrictions"],"exampleFix":"// before\n// config.yaml: tencent-cos: { bucket: \"\", region: \"\" }\nurl, key, err := cos.UploadFile(ctx, fh) // Object.Put fails with signature error\n// after\n// config.yaml: tencent-cos: { bucket: \"my-bucket-1250000000\", region: \"ap-guangzhou\", secret-id: \"...\", secret-key: \"...\" }","handlingStrategy":"retry","validationCode":"cfg := global.GVA_CONFIG.TencentCOS\nif cfg.Bucket == \"\" || cfg.Region == \"\" || cfg.SecretID == \"\" || cfg.SecretKey == \"\" {\n    return errors.New(\"tencent cos config incomplete\")\n}","typeGuard":null,"tryCatchPattern":"url, key, err := cos.UploadFile(ctx, fh)\nif err != nil {\n    if isTransientCOS(err) { // 5xx/timeout\n        // retry with backoff\n    }\n    return fmt.Errorf(\"cos upload failed: %w\", err)\n}","preventionTips":["Validate TencentCOS config at startup","Rotate credentials before expiry","Confirm VPC/network allows COS regional endpoints"],"tags":["tencent-cos","upload","object-storage","network"],"backgroundTag":"object-storage-put-failed","analyzedSha":"3136500ef380842b0eb6c4daa87c3f8a47fcf9e0","analyzedAt":"2026-08-31T13:50:02.721Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}