{"record":{"id":"09ff8446d08d2ae0","repo":"Tencent/WeKnora","slug":"failed-to-initialize-tos-client-w","errorCode":null,"errorMessage":"failed to initialize TOS client: %w","messagePattern":"failed to initialize TOS client: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/application/service/file/tos.go","lineNumber":52,"sourceCode":"\treturn NewTosFileServiceWithTempBucket(endpoint, region, accessKey, secretKey, bucketName, pathPrefix, \"\", \"\")\n}\n\n// NewTosFileServiceWithTempBucket creates a TOS file service with optional temp bucket.\nfunc NewTosFileServiceWithTempBucket(endpoint, region, accessKey, secretKey, bucketName, pathPrefix, tempBucketName, tempRegion string) (interfaces.FileService, error) {\n\tif err := utils.ValidateURLForSSRF(endpoint); err != nil {\n\t\treturn nil, fmt.Errorf(\"unsafe TOS endpoint: %w\", err)\n\t}\n\thttpConfig := utils.DefaultSSRFSafeHTTPClientConfig()\n\tclient, err := tos.NewClientV2(\n\t\tendpoint,\n\t\ttos.WithRegion(region),\n\t\ttos.WithCredentials(tos.NewStaticCredentials(accessKey, secretKey)),\n\t\ttos.WithHTTPTransport(&utils.SSRFValidatingRoundTripper{\n\t\t\tBase: utils.NewSSRFSafeTransport(httpConfig),\n\t\t}),\n\t)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to initialize TOS client: %w\", err)\n\t}\n\n\tif err := ensureTOSBucket(client, bucketName); err != nil {\n\t\treturn nil, err\n\t}\n\n\tif tempBucketName != \"\" {\n\t\tif tempRegion == \"\" {\n\t\t\ttempRegion = region\n\t\t}\n\t\t// Temporary bucket may belong to another region, so probe with a short-lived client.\n\t\ttempClient, err := tos.NewClientV2(\n\t\t\tendpoint,\n\t\t\ttos.WithRegion(tempRegion),\n\t\t\ttos.WithCredentials(tos.NewStaticCredentials(accessKey, secretKey)),\n\t\t\ttos.WithHTTPTransport(&utils.SSRFValidatingRoundTripper{\n\t\t\t\tBase: utils.NewSSRFSafeTransport(httpConfig),\n\t\t\t}),","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/application/service/file/tos.go#L34-L70","documentation":"The main TOS client construction (tos.NewClientV2) failed and is wrapped with 'failed to initialize TOS client'. This means the SDK could not build a client from the given endpoint/region/credentials/transport options — typically a malformed endpoint or an invalid client option. Note the SSRF check has already passed at this point.","triggerScenarios":"tos.NewClientV2 returning an error due to an invalid endpoint format, incompatible options, or a failure building the SSRFValidatingRoundTripper-based HTTP transport.","commonSituations":"Endpoint containing a scheme or trailing path that the TOS SDK cannot parse (SDK expects host only); empty region; SDK version mismatch with option functions (NewClientV2 API changes); misconfigured custom transport.","solutions":["Verify the endpoint is a bare host like 'tos-cn-beijing.volces.com' (no scheme, no trailing slash) as the TOS SDK v2 expects","Unwrap the error to see the SDK's specific complaint (invalid endpoint vs option error)","Check the volcengine TOS SDK v2 version matches the option helpers used (WithRegion/WithCredentials/WithHTTPTransport)","Confirm region and credentials are non-empty before construction"],"exampleFix":"// before\nendpoint := \"https://tos-cn-beijing.volces.com\" // scheme causes SDK error\nclient, err := tos.NewClientV2(endpoint, ...)\n// after\nendpoint := \"tos-cn-beijing.volces.com\" // host only\nclient, err := tos.NewClientV2(endpoint,\n    tos.WithRegion(region),\n    tos.WithCredentials(tos.NewStaticCredentials(accessKey, secretKey)))","handlingStrategy":"validation","validationCode":"if endpoint == \"\" || region == \"\" {\n    return errors.New(\"TOS endpoint and region are required\")\n}\nif strings.Contains(endpoint, \"://\") {\n    return fmt.Errorf(\"endpoint must be bare host, got %q\", endpoint)\n}","typeGuard":null,"tryCatchPattern":"svc, err := file.NewTosFileServiceWithTempBucket(...)\nif err != nil && strings.Contains(err.Error(), \"failed to initialize TOS client\") {\n    return fmt.Errorf(\"check TOS endpoint format and SDK options: %w\", err)\n}","preventionTips":["Pass bare-host endpoints (no scheme/path) to tos.NewClientV2","Pin the volcengine TOS SDK v2 version and keep option helpers matching","Validate endpoint/region/credentials non-empty before construction","Construct the service at startup so init errors surface immediately"],"tags":["tos","sdk","configuration","initialization"],"backgroundTag":"client-initialization-failed","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}