Tencent/WeKnora · error

failed to initialize TOS client: %w

Error message

failed to initialize TOS client: %w

What it means

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.

Source

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

	return NewTosFileServiceWithTempBucket(endpoint, region, accessKey, secretKey, bucketName, pathPrefix, "", "")
}

// NewTosFileServiceWithTempBucket creates a TOS file service with optional temp bucket.
func NewTosFileServiceWithTempBucket(endpoint, region, accessKey, secretKey, bucketName, pathPrefix, tempBucketName, tempRegion string) (interfaces.FileService, error) {
	if err := utils.ValidateURLForSSRF(endpoint); err != nil {
		return nil, fmt.Errorf("unsafe TOS endpoint: %w", err)
	}
	httpConfig := utils.DefaultSSRFSafeHTTPClientConfig()
	client, err := tos.NewClientV2(
		endpoint,
		tos.WithRegion(region),
		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 client: %w", err)
	}

	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),
			}),

View on GitHub (pinned to 988cbb0330)

Solutions

1. Verify the endpoint is a bare host like 'tos-cn-beijing.volces.com' (no scheme, no trailing slash) as the TOS SDK v2 expects
2. Unwrap the error to see the SDK's specific complaint (invalid endpoint vs option error)
3. Check the volcengine TOS SDK v2 version matches the option helpers used (WithRegion/WithCredentials/WithHTTPTransport)
4. Confirm region and credentials are non-empty before construction

Example fix

// before
endpoint := "https://tos-cn-beijing.volces.com" // scheme causes SDK error
client, err := tos.NewClientV2(endpoint, ...)
// after
endpoint := "tos-cn-beijing.volces.com" // host only
client, err := tos.NewClientV2(endpoint,
    tos.WithRegion(region),
    tos.WithCredentials(tos.NewStaticCredentials(accessKey, secretKey)))

if endpoint == "" || region == "" {
    return errors.New("TOS endpoint and region are required")
}
if strings.Contains(endpoint, "://") {
    return fmt.Errorf("endpoint must be bare host, got %q", endpoint)
}

svc, err := file.NewTosFileServiceWithTempBucket(...)
if err != nil && strings.Contains(err.Error(), "failed to initialize TOS client") {
    return fmt.Errorf("check TOS endpoint format and SDK options: %w", err)
}

When it happens

Trigger: tos.NewClientV2 returning an error due to an invalid endpoint format, incompatible options, or a failure building the SSRFValidatingRoundTripper-based HTTP transport.

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

Related errors

• failed to initialize TOS temp client: %w
• unsafe TOS endpoint: %w
• default HTTP transport is not *http.Transport
• custom agent configuration is required for agent QA
• summary model (model_id) is not configured in custom agent s

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