Tencent/WeKnora · error

failed to initialize TOS temp client: %w

Error message

failed to initialize TOS temp client: %w

What it means

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.

Source

Thrown at internal/application/service/file/tos.go:73

	if err := ensureTOSBucket(client, bucketName); err != nil {
		return nil, err
	}

	if tempBucketName != "" {
		if tempRegion == "" {
			tempRegion = region
		}
		// Temporary bucket may belong to another region, so probe with a short-lived client.
		tempClient, err := tos.NewClientV2(
			endpoint,
			tos.WithRegion(tempRegion),
			tos.WithCredentials(tos.NewStaticCredentials(accessKey, secretKey)),
			tos.WithHTTPTransport(&utils.SSRFValidatingRoundTripper{
				Base: utils.NewSSRFSafeTransport(httpConfig),
			}),
		)
		if err != nil {
			return nil, fmt.Errorf("failed to initialize TOS temp client: %w", err)
		}
		if err := ensureTOSBucket(tempClient, tempBucketName); err != nil {
			return nil, err
		}
	}

	return &tosFileService{
		client:         client,
		pathPrefix:     strings.Trim(pathPrefix, "/"),
		bucketName:     bucketName,
		tempBucketName: tempBucketName,
	}, nil
}

// CheckConnectivity verifies TOS is reachable by performing a HeadBucket request.
func (s *tosFileService) CheckConnectivity(ctx context.Context) error {
	checkCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
	defer cancel()

View on GitHub (pinned to 988cbb0330)

Solutions

1. Verify tempRegion matches the region of tempBucketName (do not reuse the main region blindly if buckets differ)
2. Unwrap the error to see the SDK's specific failure for the temp client
3. If the temp bucket is unused, pass empty tempBucketName/tempRegion to skip temp client creation entirely
4. Ensure temp credentials are valid and the endpoint is the bare host form the SDK expects

Example fix

// before
svc, err := file.NewTosFileServiceWithTempBucket(ep, region, ak, sk, bucket, prefix,
    "tmp-bucket", region) // tmp-bucket is actually in another region
// after
svc, err := file.NewTosFileServiceWithTempBucket(ep, region, ak, sk, bucket, prefix,
    "tmp-bucket", "cn-guangzhou") // tempRegion matches temp bucket

if tempBucketName != "" && tempRegion == "" {
    return errors.New("tempRegion required when tempBucketName is set")
}

svc, err := file.NewTosFileServiceWithTempBucket(...)
if err != nil && strings.Contains(err.Error(), "TOS temp client") {
    // degrade: retry without temp bucket if the feature is optional
    return file.NewTosFileService(endpoint, region, ak, sk, bucket, prefix)
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• failed to initialize TOS client: %w
• unsafe TOS endpoint: %w
• custom agent configuration is required for agent QA
• summary model (model_id) is not configured in custom agent s
• rerank model is not configured: please set rerank_model_id o

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