{"record":{"id":"db638b327e677861","repo":"Tencent/WeKnora","slug":"failed-to-initialize-tos-temp-client-w","errorCode":null,"errorMessage":"failed to initialize TOS temp client: %w","messagePattern":"failed to initialize TOS temp client: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/application/service/file/tos.go","lineNumber":73,"sourceCode":"\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}),\n\t\t)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to initialize TOS temp client: %w\", err)\n\t\t}\n\t\tif err := ensureTOSBucket(tempClient, tempBucketName); err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t}\n\n\treturn &tosFileService{\n\t\tclient:         client,\n\t\tpathPrefix:     strings.Trim(pathPrefix, \"/\"),\n\t\tbucketName:     bucketName,\n\t\ttempBucketName: tempBucketName,\n\t}, nil\n}\n\n// CheckConnectivity verifies TOS is reachable by performing a HeadBucket request.\nfunc (s *tosFileService) CheckConnectivity(ctx context.Context) error {\n\tcheckCtx, cancel := context.WithTimeout(ctx, 10*time.Second)\n\tdefer cancel()","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/application/service/file/tos.go#L55-L91","documentation":"When a temp bucket name is provided, a second TOS client is built for it; this error wraps that construction failure with 'failed to initialize TOS temp client'. Same failure modes as the main client but applies only to the optional temp client — likely a temp-region or endpoint problem specific to the temp bucket configuration.","triggerScenarios":"Configuring a non-empty tempBucketName whose temp region is invalid/empty, or whose construction options fail in tos.NewClientV2 for the temp client (malformed endpoint, SDK option error).","commonSituations":"Temp bucket in a different region but tempRegion left empty or wrong; copy-pasted config with placeholder temp credentials; SDK version mismatch affecting only the temp path; endpoint restrictions for the temp bucket's region.","solutions":["Verify tempRegion matches the region of tempBucketName (do not reuse the main region blindly if buckets differ)","Unwrap the error to see the SDK's specific failure for the temp client","If the temp bucket is unused, pass empty tempBucketName/tempRegion to skip temp client creation entirely","Ensure temp credentials are valid and the endpoint is the bare host form the SDK expects"],"exampleFix":"// before\nsvc, err := file.NewTosFileServiceWithTempBucket(ep, region, ak, sk, bucket, prefix,\n    \"tmp-bucket\", region) // tmp-bucket is actually in another region\n// after\nsvc, err := file.NewTosFileServiceWithTempBucket(ep, region, ak, sk, bucket, prefix,\n    \"tmp-bucket\", \"cn-guangzhou\") // tempRegion matches temp bucket","handlingStrategy":"validation","validationCode":"if tempBucketName != \"\" && tempRegion == \"\" {\n    return errors.New(\"tempRegion required when tempBucketName is set\")\n}","typeGuard":null,"tryCatchPattern":"svc, err := file.NewTosFileServiceWithTempBucket(...)\nif err != nil && strings.Contains(err.Error(), \"TOS temp client\") {\n    // degrade: retry without temp bucket if the feature is optional\n    return file.NewTosFileService(endpoint, region, ak, sk, bucket, prefix)\n}","preventionTips":["Only set tempBucketName when temp storage is actually needed; otherwise pass empty strings","Keep tempRegion in sync with the temp bucket's actual region","Validate temp credentials separately from main credentials","Surface temp-client errors distinctly in config validation at boot"],"tags":["tos","sdk","configuration","temp-bucket"],"backgroundTag":"client-initialization-failed","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}